HP 3000 Manuals

HP DeskManager Intrinsics

Concepts Behind the Intrinsics 

There are various concepts behind the way the Intrinsics work which you
should understand before you use them, notably the use of Transaction
Files and the Session Profile.

The Transaction File 

The Transaction File is used to pass messages and other items into and
out of HP Desk.  It is also used to pass information between user
applications and the Intrinsics.

The Transaction File is a collection of fixed length, fixed field
records.  Each record is called a transaction record and has a
transaction type.  Each transaction record represents one characteristic
or attribute of the message or data that it represents.


            

The Advantages of Using Transaction Files 

The Transaction File is used because it is usually impossible to pass all
the information needed by an Intrinsic in the parameters to the intrinsic
call.  For example, if we are going to pass a Distribution List or the
structure of a message, there are too many possibilities for us to define
them in one parameter string.  To get around this problem the Intrinsics
are passed the name of a Transaction File as a parameter, and this file
contains all of the information that the Intrinsic calls need.  Using a
Transaction File therefore allows the calling sequence to an Intrinsic to
be kept short.

Transaction Files are important in maintaining the flexibility of the
Intrinsics and making it possible to isolate the real Intrinsics code
from the calling application.  They are used as a two-way information
buffer between the Intrinsic call and the Intrinsics Driver process
(INTRNSON.HPMAIL.SYS), that is, the parameters are passed to an Intrinsic
using the Transaction File, and the result is returned to it.

If an application performs the same function repeatedly, the program can
use the same Transaction File over and over like a form of template.

Transaction Files are easy to use from COBOL, FORTRAN or Pascal.  No
passing of messages is required, Transaction File fields can be accessed
directly.

Transaction File Format 

Transaction Files are fixed length, binary MPE files, that can be either
permanent or temporary files.

They have a rigidly defined format.  The first record is always a
Body_Type identifier, which defines precisely what is contained in the
Transaction File.  This is followed by any number of transaction records.
Each of the following records contain the information that will be passed
to the call so that it executes as required.  The format of the file is
explained in detail in Chapter 6 .

There are many types of transaction record, some of which are applicable
to each Intrinsic call.  The ones that are applicable for each Intrinsic
call are described in Chapter 2 , Chapter 3  and Chapter 5 .
The details of each of the transaction records is described in Chapter 6
.

An easy way to build or to edit Transaction Files is to use the
Transaction File Editor (INTRNBRW.HPMAIL.SYS). The editor can be invoked
using the TFILEDIT UDC.

Transaction Files Holding Messages 

If the information being passed in a Transaction File is a message, the
content of the message is held in one or more MPE files.  Each file is
referenced from the Transaction File by a content transaction record.  A
message can be made up of a number of content files.  All HP Desk basic
items, for example, Diary items, are held in content files.

When HPDGateReceive and HPDUserReceive are used, HP Desk extracts
messages from the database, puts them into a content file and writes the
name of the content file into the tt_content_file transaction record.

When HPDGateSend and HPDUserSend are used, the user application supplies
the message in a content file and writes the name of the content file
into the tt_content_file transaction record.  HP Desk then copies the
message into its database.

A simple message supplied to HPDUserSend might include the following
transaction records:

   *   Transaction File body type identifier (tt_body_type).

   *   Item subject (tt_subject).

   *   To name and address (tt_to).

   *   Included content file name (tt_content_file).

Refer to Chapter 6  for more information about these transaction
records.

Transaction Files for Selection Requests and Results 

When an Intrinsic selects information or performs an action, the
information produced or needed to perform the action is held in the
Transaction File.  The information includes things like a list of In Tray
items to delete in HPDDeleteMsg, or directory search information in
HPDNameProbe.

When an Intrinsic returns selected information, the Transaction File
includes one transaction record for each item selected.  For example, if
you request an In Tray list, one transaction record is returned for each
selected In Tray item.

An Example Intrinsic Call 

The HPDUserSend Intrinsic is used to send a message to a user or group of
users configured in the HP Desk network.  The programmatic call made
using this Intrinsic would look like the following example:

     HPDUserSend (status, trans_file, op_type [, message_ref];

There are four distinct parts of data that are supplied to, or returned
from, this Intrinsic call:

status                A value returned by the call indicating success or
                      failure of the call.  If the call failed, status 
                      will contain an error number giving the reason for
                      the failure.

trans_file            The name of a Transaction File giving further
                      information about what actions this call is
                      supposed to perform.

op_type               Indicates what type of message is being sent.

message_ref           Returned by the Intrinsic call giving the number
                      associated with this message internally in the HP
                      Desk database.

Therefore, when we call this Intrinsic, we supply trans_file and op_type,
and status and message_ref are returned by the Intrinsic.

The Transaction File (whose name is passed in the trans_file parameter
may contain, for example, the following information:

   *   General information describing the use of the Transaction File.
   *   The subject of the item.
   *   The priority of the message.
   *   The Distribution List.
   *   Where a package begins and ends.
   *   The names of the content items in the message.

The Intrinsics Session Profile File 

This file provides configuration information at sign on time, allowing a
user's application to vary the way the Intrinsics work in particular
cases.  The Session Profile is basically a set of rules which will be
obeyed whilst the current session exists.  The use of this file is
optional.  If you don't use it, default configuration options will apply.
If your application is going to use a Session Profile file, it must
specify a file name in the HPDUserSignon or HPDGateSignon Intrinsic call.
Normally the profile will remain in force until the application signs
off, or signs on again.

The format of the Session Profile file is the same as the Transaction
File described above.  Like the Transaction File, it is stored as an MPE
file.  It has its own set of Session Profile record types as defined in
Chapter 8 .

Session Profiles can be created by your application.  As they are not
likely to change very often, and to reduce programming effort, it may be
worthwhile using the Transaction File Editor to produce a set of Session
Profile files that can be stored as MPE files and used by your
applications whenever required.

The type of information which can be specified in the Session Profile
file includes an "acceptable level of failure" indication.  This is the
level of error that can be permitted without the Intrinsic failing to
complete.  Other options define whether foreign addressing information is
to be used, the format in which the content of messages should be
extracted, and whether time information is output as local or GMT.

The HPDUtility Intrinsic provides a way of changing the current session
profile file to another without having to sign on again.

MPE/iX 5.0 Documentation