HP 3000 Manuals HP 3000 Manuals
HPDUserReceive
______________________________________________________________________________
| |
| S BA I I |
| HPDUserReceive (status, trans_file [, message_source] [, message_ref]);|
______________________________________________________________________________
HPDUserReceive allows an application to scroll through the messages in a
user's In Tray, either in sequence returning both read and unread
messages, or selectively. It may also be used to return messages in a
user's Pending Tray for tracking purposes.
status
Required by Reference; type = STATUS_TYPE.
Used to return information from the Intrinsics.
This gives the overall result of the receive. It does not matter what it
contains when the Intrinsic is called.
trans_file
Required, by Reference; type = BYTE_ARRAY, length = 36 bytes.
Used to return information from the Intrinsic and possibly to supply
information to it.
This contains the name of the Transaction File which is to hold the
details of the message. This file will be updated with the description
of the received message. The file name should be terminated with a
non-alphanumeric character other than "/" or ".". If the first character
of this parameter is an asterisk (*), HPDUserReceive returns the message
in the default Transaction File specified in the Session Profile file.
The name of the default Transaction File will be returned in trans_file.
If the first character is any other non-alphabetic character (except
space), the Intrinsic creates a randomly named Transaction File to hold
the details. The randomly created name will be returned in trans_file.
To receive selected messages from the user's In Tray or Pending Tray, a
Transaction File containing selection information must be supplied to
HPDUserReceive. This will be overwritten with the selected message. If
there is no selcetion, then a Transaction File name should not be
supplied, instead any non-alphabetical character (except a space) should
be provided (as described above).
message_source
Optional, by Reference; type = INTEGER.
Used to supply information to the Intrinsic.
This is an indicator which determines from where a message is to be
received.
0 the message is extracted from the In Tray
1 the message is extracted from the Pending Tray
If this parameter is not provided, the message is taken from the In Tray
by default.
message_ref
Optional, by Reference; type = INTEGER
Used to return information from the Intrinsic.
This is a reference number giving either the tracking number assigned to
the message by HP Desk, or, if the item is a reply or non-delivery
notification, the number assigned to the message to which these refer.
Message_ref is used to identify the message for tracking purposes. If
message_ref is not provided, this parameter is not returned.
General Information about HPDUserReceive
HPDUserReceive can be called after a successful call to HPDUserSignon.
It allows an application to receive messages or replies one at a time,
starting at the first one that arrived in the user's In Tray, or appeared
in the Pending Tray.
Each call to HPDUserReceive receives one message at a time into a
Transaction File whose name is supplied or returned as one of the
parameters.
For In Tray messages, each message is written as transaction records that
describe the elements of the message, for example, the Distribution List
names and the names of files containing the content (i.e. Part2, Part3
etc.). For Pending Tray messages, the message is also written as
transaction records that describe each message element, except that the
content part is not returned unless a Session Profile record (100700) is
supplied to indicate that this should be the case. Subsequent calls to
HPDUserReceive will move on to the next message in sequence.
HPDUserReceive also allows the selective extraction of one In Tray or
Pending Tray message at a time. Selective extraction of messages is
achieved by supplying as the second record (the tt_body-type is always
the first record in a Transaction File) in an otherwise empty Transaction
File, a suitable In Tray item or Pending Tray item selector record (types
5100 and 5200, see Chapter 6 . This record will be overwritten with
the result. The HPDUtility Intrinsic should be used to get a list of In
Tray or Pending Tray items for this purpose.
Session Profile options may be selected to request that documents within
messages are output in particular formats depending on which is the most
convenient for the receiving application. By default, all 'text
compatible' items, for example, HP Slate, HP Word, Memomaker and
AdvanceWrite, for which HP Desk supplies as standard a conversion path to
Text, and also other formats for which a converter to Text exists, will
be output as Text unless the configuration options state otherwise.
[REV BEG]
If HPDUserReceive is unable to complete a requested and valid conversion,
the item is generated unconverted. HPDUserReceive processes the message
to completion and fully generates the Transaction File. However it will
return a positive value, +5401 in status[1] as a warning.[REV END]
If a message extracted from a user's In Tray has a READ or REPLY
acknowledgment set on it, HPDUserReceive automatically generates a READ
acknowledgment to indicate to the sender of that message that it has been
processed by the recipient.
A previously read message remains in the In Tray or Pending Tray until a
call to HPDDeleteMsg is made to delete it.
The content files returned from HPDUserReceive are created in the group
and account in which the caller program is running. If the caller of the
Intrinsic did not create a Transaction File, it is also created in the
group and account in which the caller program is running. A Session
Profile option can be used to alter the group in which these files are
created.
If HPDUserReceive is not wholly successful, it will return either a
positive values in status[1] as a warning, or a negative value as an
error. Most HPDUserReceive warnings mean that the message is nearly
complete, perhaps one part could not be generated for some reason.
All HPDUserReceive errors can result in a previously existing Transaction
File being overwritten or an incomplete Transaction File being created.
The caller must delete or rewind the Transaction File as appropriate.
The message will remain in the In Tray or Pending Tray until the caller
deletes the message and continues the application. There is one
exception to this, where the following status is returned:
[REV BEG]
-1900 Unexpected error
[REV END]
This is normally caused by an Intrinsics internal error, but could also
be due to a corrupt message in the In Tray or Pending Tray. The caller
must decide whether to delete the message then inform the sender and
carry on as normal, or whether to stop the system and investigate
further.
[REV BEG]
Routed messages extracted from a user's In Tray will be automatically
passed on to the next user in the route list by HPDUserReceive. This is
to ensure that the routing sequence is not blocked, since the extracted
message cannot be progressed or rejected programatically. Messages
passed on in this way by the Intrinsics will appear the next user's In
Tray. However, an appended text in the message will make it clear that
in fact the previous user did not authorise the message.
The sp_dont_route_msgs Session Profile option indicates whether a routed
message should be automatically passed on to the next user in the route
list. If the option is set, then the message will be automatically
rejected on behalf of the application by HPDUserReceive and it will be
returned with explanatory text.
Whatever the setting of this option, if the user being processed by
HPDUserReceive is the next to last (that is the last signatory) on the
list, the relevant message will be automatically rejected on his behalf
by HPDUserReceive, and it will not reach the last user on the list. In
this case, the STATUS [1] field will return a +5420 warning to indicate
that a routed message has been extracted successfully and it has been
forwarded to the next user, and +5421 if the routed message has been
automatically rejected on behalf of the application.
[REV END]
Transaction Records Permitted with HPDUserReceive
Refer to Chapter 6 for more information on the Transaction File. The
following transaction records may be used in the Transaction File
extracted by or supplied to the HPDUserReceive Intrinsic:
1000 tt_body_type Transaction Body Type Identifier. This
transaction record must be supplied if you
are doing a selective read, and will always
be generated.
2000 tt_eu_info_format Define foreign address format. This
transaction will always be generated.
5100 tt_intray_item In Tray item. Used as an item selector. If
you are making a selection, either this or a
5200 record must be present in the supplied
Transaction File.
5200 tt_pendingtray_item Pending Tray item. Used as an item selector.
If you are making a selection, either this or
a 5100 record must be present in the supplied
Transaction File.
10000 tt_creator Sender name and address. This transaction
record will always be generated.
11000 tt_created_date_time Creation date and time. This transaction
record will always be generated.
11100 tt_subject Item Subject. This transaction record will
always be generated.
11200 tt_msg_priority Message Priority Indicator (URGENT or
NORMAL). This transaction record will always
be generated.
11300 tt_security Item Security Indicator (PRIVATE). This
transaction record will always be generated.
11400 tt_ack_level Requested acknowledgment level. This
transaction record will always be generated.
11700 tt_app_date_time Date/time/duration of appointment on message.
Only generated if applicable.
12000 tt_disallow_autof Disallow autoforward indicator. Only
generated if applicable.
12200 tt_non_del_reason Non-delivery reason indicator. Only
generated if applicable.
21000 tt_from FROM name and address. At least one
addressee will be generated (either a tt_to,
tt_cc or tt_bcc record).
21100 tt_to TO name and address. At least one addressee
will be generated (either a tt_to, tt_cc or
tt_bcc record).
21200 tt_cc CC name and address. At least one addressee
will be generated (either a tt_to, tt_cc or
tt_bcc record).
21300 tt_bcc BCC name and address. At least one addressee
will be generated (either a tt_to, tt_cc or
tt_bcc record).
30100 tt_start_package Start Package definition. Only generated if
applicable.
30200 tt_package_creator Package creator. Only generated if
applicable.
30400 tt_item_creator Item creator. Only generated if applicable.
30500 tt_content_file Content filename, filecode and subject. Only
generated if applicable.
39000 tt_end_package End Package definition. Only generated if
applicable.
200000 tt_referenced_file Referenced file identifier. Only generated
if applicable.
Session Profile Options Relevant to HPDUserReceive
Refer to Chapter 8 for more information on the Session Profile file.
These Session Profile options can be used to change the operation of the
HPDUserReceive Intrinsic:
100100 sp_extra_user_info Define foreign address format
100200 sp_convert Define output document format
100210 sp_convert_target Convert all documents to a specified filecode
type
100300 sp_max_size Maximum size of message to be extracted
100500 sp_time Output times in GMT (rather than local) time
100700 sp_pendtray_content Output content of messages from the Pending
Tray
100800 sp_def_transfile Default Transaction File definition
101100 Destination Group for received files[REV BEG]
sp_destination_group
101200 sp_dont_route_msgs Passing on routed messages[REV END]
Status Returns Specific to HPDUserReceive
-400 Cannot access first parameter
-401 Cannot access second parameter
-402 Cannot access third parameter
-403 Cannot access fourth parameter
-500 Application does not have PH capability
-501 Application does not have DS capability
-502 User does not have SF capability
-1000 HPDUserSignon has not yet been called successfully
-1003 HP Desk is not available
-1004 The HP Desk Intrinsics product is not installed
-1005 HP Desk Intrinsics software and message catalogue
are incompatible
-1007 HP Desk User Intrinsics sessions are disabled
-1009 No MPE system resource (CreateProcess Error 4)
-1010 Cannot load Intrinsics Driver program
(CreateProcess Error 16)
-1011 HP Desk and HP Desk Intrinsics software versions
are incompatible
-1100 Cannot access Transaction File (see STATUS[6] for
FS err)
-1101 Cannot create Transaction File
-1114 The Transaction File is too small (end of file
encountered)
-1115 The record size of the Transaction File is too
small
-1116 A Transaction Filename must be supplied
-1202 No message found matching message selector
-1205 Insufficient HP Desk capability (no read
capability)
+1119 Warning condition: No errors have occurred but a
transaction record has been marked with a warning
status to indicate an unexpected non-serious
condition
-1121 No default Transaction File name defined
-1123 Named Transaction File does not exist
-1124 Transaction File has a bad file code
-1900 Unexpected error
-1902 Insufficient disc space
-1903 Insufficient group space
-1904 Insufficient account space
-1905 System directory overflow
-1906 Temporary directory overflow
-5000 Message source is invalid
+5400 There are no (more) messages to receive
+5401 Items not converted - conversion failed
-5402 Message is larger then the size allowed through the
gateway
-5403 Insufficient disc space to hold message
-5406 A composite item was found that contained too many
nested items (more than 50)
+5416 Warning! One or more foreign address fields
truncated due to insufficient allocated in
transaction record
+5417 Warning! Ouput message contains encrypted items
+5418 Warning! This is a Principal's private message[REV
BEG]
+5420 Warning! A routed message has been extracted
successfully and has been forwarded to the next
user in the route list
+5421 Warning! The routed message has been automatically
rejected on behalf of the application[REV END]