HP 3000 Manuals

HP DeskManager Intrinsics

Session Profile Record Formats 

The First Sixteen Bytes 

The first 16 bytes of all records always takes this format:

Bytes  Data Type Contents 

1 - 4            Reserved for future use

5 - 8  Integer   Transaction record type

9 -12  Integer   Result field

13-16            Reserved for future use

17 on            Contents dependent on Session Profile
                 record type

These fields are used in the same way as in the Transaction File
described in Chapter 6 .

The characteristics of the rest of the record depend on the type of
record it is.  Sometimes the remainder of the record is empty.

For example, the first 16 bytes could look like this:


            

100010 - Acceptable Failure Indicator (sp_accept_fail) 

This record allows you to determine the level of failure that can occur
when a message, Transaction File etc., is being processed by an
Intrinsic.

If a higher level of failure than that specified is reached, a negative
value is returned in status[1] and the message is not sent.

If errors occur within processing but fall within the bounds of
acceptable failure the message is sent, though the transactions in error
are ignored.  The main Intrinsic status return (status [1]) signifies
partial success with a positive value.

In both cases, the result fields of the relevant records are updated with
a code representing the nature of the error.

The other fields returned by the Intrinsic (status [3] and status [4])
identify respectively, the number of errors found in the file and the
record number (position in the file) of the first record in error.

Bytes  Data Type Contents 

17-20  Integer   [REV BEG]Badly formed names or if the
                 nodename is missing non-configured
                 names in submitted message
                 Distribution Lists (input only):[REV
                 END]
                 0 Accept (default)
                 1 Reject

20-24  Integer   Non-configured or badly formed nodes
                 in submitted message Distribution
                 Lists, they won't be delivered to
                 (input only):
                 0 Accept (default)
                 1 Reject

25-28  Integer   Non-existent or inaccessible files
                 holding the content of a message etc.
                 (input only):
                 0 Reject (default)
                 1 Accept

For example, an sp_accept_fail Session Profile record could look like
this:


            

100100 - Use Additional User Information Fields (sp_extra_user_info) 

This record indicates that extra information needs to be accepted and/or
passed back by the Intrinsics with each name/address.  The information is
either used to identify a user uniquely from details held in the HP Desk
directories (for example, foreign address aliases) or it can simply be
supplementary information which can be used to qualify a name/address
(for example, an explicit foreign address).  Remember that aliasing is
only relevant when the application is signed on to a gateway.

Each option is defined using a pair of adjacent integer fields.  The
first integer defines what information is required, the second the length
of the field in bytes (a multiple of 4) that should be reserved in the
name/address transaction record (see tt_creator, tt_to records etc.  in
Chapter 6 .  This does not affect the internal storage of the
additional address information within HP Desk, it merely limits the
amount of space allocated in the Transaction File to supply and return
that information.

The order in which the options are defined in this Session Profile record
defines the order in which the details appear in the name/address
records.  After the last option, the remainder of the record should be
filled with zeros.

If this Session Profile record does not exist, for performance reasons
and ease of use, the default is that additional user information in
name/address fields is neither read on input nor generated on output.


NOTE  For implementation reasons, any foreign addresses embedded within a
      name are always returned, whether or not this Session Profile
      record is supplied.


Bytes  Data Type Contents 

17-20  Integer   Option 1 type

21-24  Integer   Option 1 length (in bytes)

25-28  Integer   Option 2 type

29-32  Integer   Option 2 length (in bytes)

etc...

Values for Option type are:

           "Search" items
           1 - Foreign address aliases

           "Supplementary" items
           10 - Explicit foreign addresses

For example, if an sp_extra_user_info record has the following values:


            

All name/address fields would be formatted as follows:

Bytes  Data Type Contents 

37     Byte      Name
-144   array

145-   Byte      Mailnode
152    array

153-   Byte      Foreign address alias
192    array

193-   Byte      Explicit foreign address
232    array

100200 - Output Document Format Selector (sp_convert) 

This record specifies that an item extracted using HPDUserReceive or
HPDGateReceive contains a document of a specified format and an attempt
should be made to convert it to the target document format given in this
record.  The conversions available depend on the converters installed on
the HP Desk system.  All items that are converted on output are marked in
the tt_content_file record with the filecode of the original file.

If you wish, your document can go through intermediate conversions before
it reaches its final form.  In this session profile record you can
specify up to 6 conversions.  For example, you may want to convert an
AdvanceWrite document to TEXT and the resulting TEXT document to DCA.

If neither a 100200 nor a 100210 Session Profile record exists, documents
can only be converted into HP Desk readable TEXT. This means that by
default any document types for which a converter to TEXT exists will be
converted to TEXT. Other file types in messages will be output in their
original format.

Once you specify a 100200 Session Profile record, the default of
conversion to TEXT is switched off for all document types, even though
they do not appear in a 100200 record.  For instance, you might use a
100200 record to indicate that Memomaker documents must be converted to
HP Word documents.  If HPDUserReceive or HPDGateReceive then extracts a
message containing any other document types, apart from Memomaker, those
other document types will not be converted to TEXT (or anything else) in
the resulting message.

If there is a 100200 and a 100210 record in a Session Profile file, the
order in which they appear is significant.  When a document is to be
converted, the Intrinsics scan down the Session Profile convert
transactions and use the first valid conversion that they find for the
document.


NOTE  If new converters are added to the system after the Intrinsics are
      installed, you may need to change the Session Profile file to
      reflect this.


Bytes  Data Type Contents 

17 -   Integer   Number of conversions, normally 1
20               although can be any value from 1 to 6.

21 -   Integer   Filecode of document type for which a
24               conversion is required.

25 -   Integer   Filecode to which document should be
28               converted.

29 -   Integer   Optional, filecode to which document
32               should be further converted.

33 -   Integer   Optional, filecode to which document
36               should be further converted.

37 -   Integer   Optional, filecode to which document
40               should be further converted.

41 -   Integer   Optional, filecode to which document
44               should be further converted.

45 -   Integer   Optional, filecode to which document
48               should be further converted.

For example, to convert an AdvanceWrite document to TEXT and the
resulting TEXT document to DCA, the sp_convert Session Profile record
would look like this:


            

100210 - Convert all Documents to a Specified Filecode Type 
(sp_convert_target) 

This record specifies that an item extracted using HPDUserReceive or
HPDGateReceive contains one or more documents which should be converted
to the target document format given in this record.  The conversions
available depend on the converters installed on the HP Desk system.  All
items that are converted on output are marked in the tt_content_file
record with the filecode of the original file.

If neither a 100200 nor a 100210 Session Profile record exists, documents
can only be converted into HP Desk readable TEXT. This means that by
default any document types for which a converter to TEXT exists will be
converted to TEXT. Other file types in messages will be output in their
original format.

If there is a 100200 and a 100210 record in a Session Profile file, the
order in which they appear is significant.  When a document is to be
converted, the Intrinsics scan down the Session Profile convert
transactions and use the first valid conversion they find for the
document.


NOTE  If new converters are added to the system after the Intrinsics are
      installed, you may need to change the Session Profile file to
      reflect this.


Bytes  Data Type Contents 

17 -   Integer   Filecode of document to which all
20               documents are converted if possible

Note that documents are not converted if you put a 0 in this field.

For example, an sp_convert_target Session Profile record to convert files
to HP Word would look like this:


            

100300 - Maximum Size of Message to be Extracted (sp_max_size) 

This record allows the user to place a limit on the size, in Kilobytes,
of messages that can be extracted using HPDUserReceive or HPDGateReceive.
If an item is found which exceeds this limit, the returned status
parameter indicates this and the content is not extracted, only Group 1,
2 and 3 records appear in the returned Transaction File.  The calling
application can then take appropriate steps to deal with the message, for
example by returning a suitable non-delivery warning message back to the
sender.

Bytes  Data Type Contents 

17 -   Integer   Maximum size of message permitted in
20               kilobytes.  The default is the maximum
                 size of item permitted in the HP Desk
                 system.

21 on            Reserved for future use.

For example, an sp_max_size Session Profile record could look like this:


            

100500 - Time Processing Option (sp_time) 

This defines whether time information is to be handled as LOCAL time or
GMT. By default all times are in LOCAL format.

Regardless of how this profile option is set, those records in which a
GMT offset appears on output still appear in GMT format.

Bytes  Data Type Contents 

17 -   Integer   Time option:
20               0 use LOCAL time
                 1 accept/output time as GMT

21 on            Reserved for future use.

For example, an sp_time Session Profile record could look like this:


            

100600 - Wait on Arrival of Messages (sp_message_wait) 

This is only used with HPDGateReceive.  It indicates that a call to
HPDGateReceive should wait for the arrival of messages on the signed on
gateway if there are not messages already waiting.

By default, if this record is not set otherwise, and there are no
messages waiting to be extracted from the gateway, control is passed back
immediately to the calling application with the status parameter set to
indicate there were no messages.

If this Session Profile option is set, HPDGateReceive waits up to the
maximum time specified in the record, subject to a maximum of 60 minutes,
or until a shutdown request is issued to the Driver process.  If no
messages have arrived by then, a suitable shutdown status is returned.

Bytes  Data Type Contents 

17 -   Integer   Message wait indicator:
20               0 Return to calling program
                 immediately (Default).
                 1 Wait until message arrives, up to a
                 maximum time as stated in the next
                 field.

21 -   Integer   Wait period in minutes, if greater
24               than 60 minutes, then will default to
                 0.  That is, control will be returned
                 immediately to the calling
                 application.

25 on            Reserved for future use.

For example, an sp_message_wait Session Profile record could look like
this:


            

100700 - Contents Extraction from Pending Tray (sp_pendtray_content) 

This is only used with HPDUserReceive.  It indicates that when messages
are extracted from the Pending Tray, their content should also be
extracted from the HP Desk database and referenced in the Transaction
File.  When the default setting is taken, this does not happen.
Normally, messages are only extracted from the Pending Tray for tracking
purposes, that is, to determine who has received or read the message
etc., in which case the content is of no importance.  However, it may be
necessary to extract the content of the message if it is a forms message
and a recipient has not provided an adequate level of acknowledgment,
meaning the message has not been moved to the In Tray automatically.

Bytes  Data Type Contents 

17 -   Integer   Extract content of Pending Tray
20               messages indicator:
                 0 return only Groups 1, 2 and 3
                 transactions (i.e.  no content).  This
                 is the default.
                 1 return complete message from Pending
                 Tray (including groups 4 and T
                 transactions).

21 on            Reserved for future use.

For example, an sp_pendtray_content Session Profile record could look
like this:


            

100800 - Default Transaction File (sp_def_transfile) 

This allows a default Transaction File to be defined.  It will be opened
by the Intrinsics at sign on time and held open until sign off.  If the
Utility Switch Profile facility is used, the file is opened at this time
and closed at the next switch or sign off.

Using this file improves performance because it removes the need for a
file open and close on each transaction call.

If this Session Profile option is not specified, a default Transaction
File is not used.

Bytes  Data Type Contents 

17     Byte      Name of the default Transaction File.
-116   Array     The file must exist and be accessible
                 according to the rules stated in
                 Chapter 9  for standard Transaction
                 Files.

117 on           Reserved for future use.

For example, an sp_def_transfile Session Profile record could look like
this:


            


WARNING  For the current release of the Intrinsics, the default
         Transaction File feature is not supported.  Hence this Session
         Profile record MUST NOT be used.


100900 - Alter Name/Address Checking (sp_name_addr_checks) 

This minimizes the amount of processing done on names and addresses in
messages supplied to HPDGateSend and so provides performance
improvements.  If this option is selected, only the format of recipient
names and addresses are checked (that is, length, validity of characters
etc.).

The mailnode is not checked for existence in the directory.  Also if the
mailnode is missing, the name will not be checked for existence in the
directory.  This option must therefore be used carefully.


NOTE  The operation of HPDNameProbe is not affected by this option.
      However, it does override any settings related to name and address
      validation defined in the "acceptable level of failure" option.


Bytes  Data Type Contents 

17 -   Integer   Names/address checking indicator.
20               0 standard checking (that is mailnode
                 always, and names as well if the
                 mailnode is not supplied).
                 1 reduced checking (name and mailnode
                 formation only).

21 on            Reserved for future use.

For example, an sp_name_addr_checks Session Profile record could look
like this:


            

101100 - Destination Group for Received Files (sp_destination_group) 

This is relevant to any Intrinsic which creates content files.  It
specifies the user group in which they should be created.  If this
Session Profile record is not supplied the content file will be created
in the group in which your application is running.

Users can ask any Intrinsic which creates Transaction Files to provide
names for those Transaction Files.  This is done by placing a
non-alphabetic character, other than an asterisk (*) in the first
byte of the trans_file parameter to the Intrinsic call.  If an
sp_destination_group Session Profile record is also provided, the
Transaction File will be created in the group specified in it.  If this
Session Profile record is not specified, the Transaction File is created
in the group in which the application is running.


NOTE  Any groups you want to use must have been created in the account
      before you run the Intrinsic.


Bytes  Data Type Contents 

17 -   Byte      MPE group name
24     Array

For example, an sp_destination_group Session Profile record could look
like this:


            
[REV BEG]

101200 - Pass on routed message (sp_dont_route_msgs) 

This defines whether or not a routed message will be automatically passed
on to the next user in the route list.

Bytes  Data Type Contents 

17 -   Integer   If it is a 1, HPDUserReceive and
20               HPDGateReceive will automatically
                 reject a routed message requiring
                 action on behalf of the
                 application--the message will not be
                 automatically passed on to the next
                 user in the route list.  If the value
                 is zero (the default), the message
                 will be automatically forwarded onto
                 the next user in the route list.

For example, an sp_dont_route_msgs Session Profile record could look like
this:


            
[REV END]

MPE/iX 5.0 Documentation