HP 3000 Manuals HP 3000 Manuals
HPDGateReceive
_____________________________________________________________________________
| |
| S BA I R I |
| HPDGateReceive (status, trans_file, op_type, to_node [, message_ref]);|
_____________________________________________________________________________
HPDGateReceive allows an application to receive messages, replies or
acknowledgments left on the mail node queues associated with the signed
on gateway.
status
Required, by Reference; type = STATUS_TYPE
Used to return information from the Intrinsic.
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 (*), HPDGateReceive 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.
op_type
Required, by Reference; type = INTEGER
Used to supply information to the Intrinsic.
This defines the way messages are to be extracted by the Intrinsic. Only
one method is supported in this release of the Intrinsics, so this
parameter should be set to 0.
to_node
Required, by Reference; type = RECORD, length = 8 bytes.
Used to return information from the Intrinsic.
This returns the name of the mailnode for which the message is destined.
The first 6 bytes contain the location code and the remaining 2 the
sublocation code, each space filled where necessary.
When using COBOL, the parameter should be defined like HPD-NODE, in the
COBOL copy libraries. The FORTRAN parameter has to be defined as
HPD_NODE with the corresponding equivalence statements given in the
FORTRAN include files. The Pascal parameter should be of type
HPD_NODE_TYPE, as defined in the Pascal include files.
message_ref
Optional, by Reference; type = INTEGER
Used to return information from the Intrinsic.
This is a returned reference number, giving the tracking number assigned
by HP Desk to the message (if the item extracted is an acknowledgment,
reply or non-delivery notification, it is the tracking number assigned to
the message to which these refer). This number is used to identify the
message for tracking purposes. If message_ref is not provided, this
parameter is not returned.
General Information about HPDGateReceive
HPDGateReceive can be called after a successful call to HPDGateSignon and
can be used by an application to extract messages, replies and
acknowledgments, one at a time from a node queue associated with the
signed on gateway. The message is returned in the Transaction File which
can either be supplied by the application or created by HPDGateReceive.
If the name of the Transaction File passed in the trans_file parameter is
the name of a file which has been used before and still has values in it,
these values will be overwritten with a description of the message.
Selective extraction of messages is not available.
HPDGateReceive interacts with the Gateway manager program to determine
from which mailnode messages should be extracted first, on the basis of
number and urgency of messages. Successive calls to HPDGateReceive
return the remaining messages destined for the same mailnode until they
have all been processed, or until the Gateway manager program determines
that another mailnode should be processed instead. This might happen if,
for example, some urgent mail has arrived on another mail node. The
to_node parameter contains the name of the mailnode for which any
particular message is destined.
NOTE A message previously read by HPDGateReceive remains on the mailnode
queue until a call to HPDDeleteMsg is made to delete it.
HPDGateReceive always extracts the message at the front of the
mailnode queue and if the message is not deleted, subsequent calls
to HPDGateReceive will return the message again.[REV BEG] In this
case the application should not call HPDDeleteMsg, but should flag
the problem as needing attention.[REV END]
A message appears only once on a mailnode queue, regardless of the number
of recipients addressed on the node. It is the application's
responsibility to ensure that each recipient receives a copy. Each
message, no matter where it is destined, contains a full Distribution
List, and those recipients who reside on the node whose queue the message
is in are distinguished in the recipient transaction record (tt_from,
tt_to, tt_cc or tt_bcc) by a "deliver to this user" indicator. The same
message can appear on the gateway several times, once on each of several
node queues, therefore each will be destined for a different mailnode
address.
The arrival of messages on a mailnode queue routed through the gateway
will not be made known directly to the application. However, by using a
Session Profile option, it is possible to direct the HPDGateReceive call
to wait until a message appears for the signed on gateway, or until a
specified period of time has elapsed. By default, the Intrinsic returns
control to the calling application immediately if there is no waiting
message.
The operation of HPDGateReceive can be modified by using Session Profile
options. For example, the formats in which the content part of the
message are to be output can be defined. 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 Session Profile options state otherwise.
[REV BEG]
If HPDGateReceive is unable to complete a requested and valid conversion,
the item is generated unconverted. HPDGateReceive 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]
In addition, the format of address information for message recipients is
selectable by Session Profile option. This can be just a mailnode (the
default), or can include foreign address or alias information where this
exists.
Content files and Transaction Files are created in the group and account
in which the calling application is running. A Session Profile option
can be used to alter the group in which these files are created.
[REV BEG]
If the sender of the message retrieved by HPDGateReceive is defined as a
local user on the database at the gateway machine and an acknowledgment
is requested, HPDGateReceive generates a Transmitted Acknowledgment.[REV
END]
If HPDGateReceive is not wholly successful, it will return either a
positive value in status[1] as a warning, or a negative value as an
error. Most HPDGateReceive warnings mean that the message is nearly
complete, perhaps one part could not be generated for some reason.
Once HPDGateReceive has been called, there are a few types of error that
can occur. All HPDGateReceive errors can result in an existing
Transaction File being overwritten, or an incomplete Transaction File
being created. The caller must delete or rewind the Transaction File as
appropriate. An error of this kind would occur if, for example, a
message is too big to be received.
In most error cases, the message will remain on the node queue until the
caller resolves the problem and continues the application. There are two
exceptions to this:
* If an HP Schedule request is sent to the gateway, HPDGateReceive
moves it to the error queue and sends a non-delivery notification.
The following status is returned:
-5404 sres_disallowed_message Message not allowed to pass through
the gateway (for example, a server message)
The caller should simply process any Transaction File and continue
with the next message.
* If an error occurs due to an Intrinsics internal error, or a
corrupt message on the node queue, the following status is
returned:
-1900 sres_unex_error Unexpected error
The message is deferred by moving it to the Deferred Queue. The
application does not need to delete the message, and can continue
to receive other messages. Once all normal and urgent messages
have been processed, HPDGateReceive will make another attempt to
generate the deferred message.
[REV BEG]
For the routing and authorization capability, the HPDGateReceive sets the
routed message indicator in extracted messages. The Intrinsic will by
default also pass routed messages to the next user in the routing list,
which can be stopped by setting the sp_dont_route_messages Session
Profile option. If this is set, or the user is the last signatory on the
route list, then the message will be automatically rejected on behalf of
the user to which it is being sent. It will then be returned to the
sender with an explanatory note.
The STATUS [1] field will return a warning in both of the above
circumstances. +5420 indicates that a routed message has been extracted
successfully, and it has been forwarded to the next user in the route
sequence, and +5421 if the routed message has been successfully rejected
on behalf of the application.
HPDGateReceive also outputs a tt_hop_count record for all the messages
that are extracted. This record indicates the number of machines that
the message has passed through to reach this point. The application may
wish to act upon this field if the hop-count has reached an excessive
number.[REV END]
NOTE See Chapter 9 for installation information for HPDGateReceive.
It is essential that the action described in Chapter 9 is
followed, or HPDGateReceive will not work properly.
Transaction Records Permitted with HPDGateReceive
Refer to Chapter 6 for more information on the Transaction File. The
following transaction records may be used in the Transaction File
extracted by the HPDGateReceive Intrinsic:
1000 tt_body_type Transaction File body type Identifier.
2000 tt_eu_info_format Format of extra user information
10000 tt_creator Message sender/creator name and address.
10500 tt_msg_source Message source indicator (for HP use only).
11000 tt_created_date_time Creation date and time of the message.
11100 tt_subject Item Subject.
11200 tt_msg_priority Message Priority Indicator (URGENT or
NORMAL).
11300 tt_security Item Security Indicator (PRIVATE).
11400 tt_ack_level Requested acknowledgment level.
11500 tt_message_id Internal message ID.
11510 tt_ack_id Internal message acknowledgment.
11700 tt_app_date_time Date/time/duration of appointment
12000 tt_disallow_autof Disallow autoforward indicator
12100 tt_non_delivery Action on non-delivery indicator.
12200 tt_non_del_reason Non-delivery reason indicator
21000 tt_from FROM name and address
21100 tt_to TO name and address
21200 tt_cc CC name and address
21300 tt_bcc BCC name and address
30200 tt_package_creator Package creator
30400 tt_item_creator Item creator
30100 tt_start_package Start Package definition
30500 tt_content_file Content filename, filecode and subject
39000 tt_end_package End Package definition
200000 tt_referenced_file Referenced File
Session Profile Options Relevant to HPDGateReceive
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
HPDGateReceive Intrinsic:
100100 sp_extra_user_info Return explicit foreign addresses and/or
aliases (if present)
100200 sp_convert Define output format of content
100210 sp_convert_target Convert all documents to a specifed type
100300 sp_max_size Maximum size of message to be extracted
100500 sp_time Return times in GMT (rather than local)
format
100600 sp_message_wait Wait for arrival of messages (rather than
return control to calling application
immediately)
100800 sp_def_transfile Use default Transaction File
101100 Destination group from received files[REV
sp_destination_group BEG]
101200 sp_dont_route_msgs Pass on routed messages[REV END]
Status Returns Specific to HPDGateReceive
-400 Cannot access first parameter
-401 Cannot access second parameter
-402 Cannot access third parameter
-403 Cannot access fourth parameter
-404 Cannot access fifth parameter
-500 Application does not have PH capability
-501 Application does not have DS capability
-502 User does not have SF capability
-1001 Application is not signed on as a gateway
-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
-1008 HP Desk Gateway Intrinsics sessions are disabled
-1009 No MPE system resource (CreateProcess Error 4)
-1010 Cannot load Intrinsics Driver program
(CreateProcess Error 16)
-1011 HP Desk Intrinsics software and message catalogue
are incompatible
-1100 Cannot access Transaction File (see STATUS[6] for
FS err)
-1101 Cannot create Transaction File
-1114 Transaction File too small (end of file
encountered)
-1115 The record size of the Transaction File is too
small
-1116 A Transaction File name must be supplied
+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
-1200 Invalid op type
-1205 Insufficient HP Desk capability (no read
capability)
-1900 Unexpected error
+5400 No (more) messages to be received
+5401 Message generated although one or more item
conversions failed
-5402 Message is larger than the size allowed through the
gateway
-5403 Insufficient disc space to hold message
-5404 Message not allowed to pass through the gateway
(for example a server message)
-5405 No nodes routed through currently signed on gateway
-5406 Message contains more than the maximum number of
nested levels allowed (more than 50)
-5413 No more gateway sessions can use HPDGateReceive -
maximum number of concurrent gateways exceeded
-5414 No more gateway sessions can use HPDGateReceive -
maximum number of concurrent Drivers exceeded
-5415 No more gateway sessions can use HPDGateReceive -
maximum number of mailnodes exceeded
+5416 Warning! One or more foreign address fields
truncated due to insufficient allocated in
transaction record
+5417 Warning! Ouput message contains encrypted
items[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]