HP 3000 Manuals HP 3000 Manuals
HPDGateSend
________________________________________________________
| |
| S BA I |
| HPDGateSend (status, trans_file [, message_ref]);|
________________________________________________________
HPDGateSend allows an application to send messages, replies and
acknowledgments to users on the HP Desk network on behalf of any user
associated with the gateway specified in the HPDGateSignon call. The
message may include any form of standard MPE files except KSAM and
privileged files.
status
Required, by Reference; type = STATUS_TYPE.
Used to return information from the Intrinsic.
This gives the overall result of the HPDGateSend. 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 supply information to the Intrinsic.
This contains the name of the Transaction File holding the details of the
message. The filename should be terminated by a non-alphanumeric
character other than "/" or ".". If the first character of this
parameter is an asterisk (*), then the details of the message will be
taken from the default Transaction File specified in the Session Profile
file.
message_ref
Optional, by Reference; type = INTEGER.
Used to return information from the Intrinsic.
This is a returned reference number which gives a tracking number
assigned by HP Desk to a message. This number is used to identify the
message for tracking purposes. If message_ref is not specified, this
number is not returned.
General Information about HPDGateSend
[REV BEG]
HPDGateSend may be used after a successful call to HPDGateSignon. It is
used to send one message at a time to users on the HP Desk network from
the gateway named in the HPDGateSignon call. A message creator or sender
name and node must be specified. The node must be one that is routed out
through the gateway and HPDGateSend will check this, for security
reasons. For example, local HP OpenMail mailnodes that are to be sent to
from HP Desk users should be configured as remote nodes in HP Desk and
routed through the configured gateway to HP OpenMail. It is important to
keep your gateway password secure, as no checks are done on the creator
name of the message. A user with the gateway password could send a
message with any creator name. Details of the message are contained in
the Transaction File whose name is also passed as a parameter and which
must have been set up previously by the calling application.[REV END]
The referenced Transaction File must contain at least one recipient name
and will normally contain at least one reference to a content file,
except if it is an acknowledgment. The content file may be of any MPE
file type, except KSAM or privileged. Package structures can be defined
in the message. The construction of the forms package is described in
Chapter 6 (in the examples at the end of the chapter).
HPDGateSend can be used to send messages to HP Desk servers, such as the
Distribution List Server and the Remote Directory Updates Server.
The rules used to validate names and addresses supplied in the
Distribution List are given in Chapter 9 . In order to gain
performance improvements, it is possible to reduce the amount of checking
on names and addresses by using a Session Profile option. You may want
to do this if an application creating messages for distribution over the
HP Desk network has access to its own directory. However, this facility
must be used very cautiously as it is assumed that the information
presented to the Intrinsic is valid in HP Desk terms. Any incorrect
information will not be detected until the messages reach the HP Desk
network and may result in non-delivery or incorrect delivery.
Another Session Profile option allows the application to select whether
or not messages containing certain errors are sent anyway. For instance,
you may select whether a message with one invalid Distribution List entry
is sent to the other recipients, or not.
Messages can be sent to a predefined Distribution List by using
appropriate transaction types. The Driver process first searches the
List Area of the Default User and then the relevant Public Distribution
Lists folder.
If any recipients of the message are on the same system as that in which
HPDGateSend is being called, this Intrinsic automatically generates a
receipt acknowledgment according to standard HP Desk conventions. The
acknowledgment may be extracted in a subsequent call to HPDGateReceive.
The size of messages sent using HPDGateSend is checked against the
maximum size information specified in MAILCONFIG's Local Control Data
menu. Both the size of individual message items and the maximum number
of items is checked.
NOTE HPDGateSend does not delete the files used to construct the message
once it has been successfully sent. It is the responsibility of
the application to deal with this.
Broadly speaking, two classes of error can result from a call to
HPDGateSend:
* A warning
* A failure.
Warnings are regarded as non-fatal. In this case, the value of Status[1]
is positive and the message is sent, ignoring any transactions in error.
For instance, if an unknown node is supplied on a ''tt_to'' transaction,
and the application has specified in the Session Profile that this is an
acceptable failure, the message will be sent to the other valid
recipients.
Failures are regarded as fatal errors. The returned value of Status[1]
is negative, and the message is not sent.
In both these cases, the user application should analyse the error detail
and take some action, such as informing the sender that the message was
partly or wholly unsuccessful.
When HPDGateSend detects an error in the Transaction File, it will
attempt to validate the rest of the file. Values in the status parameter
will indicate how many errors were detected, and the position of the
first error. If errors are detected in the Transaction File, HPDGateSend
will usually return a value of -1110 in status[1] if at least one error
was fatal. If all error are warnings, status[1] will usually be set to
+1120.
In both warning and failure situations, the user application should
examine the status parameter to determine if any transactions have
errors, and if so, scan the Transaction File to analyse, and act upon,
the result fields in the invalid transactions.
[REV BEG]
For the routing and authorization capability, HPDGateSend will interpret
the tt_hop_count record. If this transaction is not supplied, or is a
negative value, an initial hop-count of 0 will be applied to the HP Desk
message.[REV END]
Transaction Records Permitted with HPDGateSend
Refer to Chapter 6 for more information on the Transaction File. The
following transaction records may be used in the Transaction File
submitted to the HPDGateSend Intrinsic:
1000 tt_body_type Transaction Body Type Identifier. This
record must be supplied.
2000 tt_eu_info_format Format of extra user information.
10000 tt_creator Message sender/creator name and address
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 Message Security Indicator (PRIVATE)
11400 tt_ack_level Requested acknowledgment
11500 tt_message_id Message Identification Information
11510 tt_ack_id Acknowledgment Identification Information
11700 tt_app_date_time Date/time/duration of appointment on
message[REV BEG]
11800 tt_hop_count The number of machines that the message has
passed through to reach this point[REV END]
12000 tt_disallow_autof Disallow Autoforward Indicator
12100 tt_non_delivery Non-delivery action indicator
12200 tt_non_del_reason Non-delivery reason indicator
21000 tt_from FROM name and address. At least one
addressee must be supplied (either a tt_to,
tt_cc, tt_bcc or tt_from record).
21100 tt_to TO name and address. At least one addressee
must be supplied (either a tt_to, tt_cc,
tt_bcc or tt_from record).
21200 tt_cc CC name and address. At least one addressee
must be supplied (either a tt_to, tt_cc,
tt_bcc or tt_from record).
21300 tt_bcc BCC name and address. At least one addressee
must be supplied (either a tt_to, tt_cc,
tt_bcc or tt_from record).
21400 tt_use_distlist A Distribution List of recipients
30100 tt_start_package Start Package definition
30200 tt_package_creator Package creator
30400 tt_item_creator Item creator
30500 tt_content_file Content filename, filecode and subject.
39000 tt_end_package End Package definition
Session Profile Options Relevant to HPDGateSend
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
HPDGateSend Intrinsic:
100010 sp_accept_fail Acceptable Failure indicator
100100 sp_extra_user_info Accept specified explicit and/or alias
foreign addresses
100500 sp_time Accept times in GMT (rather than local)
format
100800 sp_def_transfile Use default Transaction File
100900 sp_name_addr_checks Alter name/address checking
Status Returns Specific to HPDGateSend
-400 Cannot access first parameter
-401 Cannot access second parameter
-402 Cannot access third 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 user
-1003 HP Desk is not available
-1004 HP Desk Intrinsics not installed
-1005 HP Desk Intrinsics software and message catalogue
are incompatible
-1006 Could not bring message in as a dataset is full
-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 and HP Desk Intrinsics software versions
are incompatible
-1100 Unable to access Transaction File (see STATUS[6]
for FS err)
-1110 One or more transaction records has an invalid
field
-1111 Transaction records are out of sequence, or a
transaction has an invalid type
-1112 The Transaction File is empty
-1116 A Transaction File name must be supplied
-1118 Unexpected records at end of Transaction File
+1119 Warning! Message sent although one or more
transaction records has an invalid field
+1120 Warning! Message sent although one or more
transaction records has an error, allowed by the
Session Profile sp_accept_fail transaction
-1900 Unexpected error
-3400 Message has no recipients
-3406 The Transaction File is incomplete
-3409 Start package transaction has no corresponding End
package transaction
-5402 Message is larger than the size allowed through the
gateway