HP 3000 Manuals HP 3000 Manuals
HPDUserSend
____________________________________________________________________
| |
| S BA I I |
| HPDUserSend (status, trans_file [, op_type] [, message_ref]);|
____________________________________________________________________
HPDUserSend allows an application to send, forward or reply to one HP
Desk message at a time on behalf of the signed on user. The message may
contain 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 send. 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.
op_type
Optional, by Reference; type = INTEGER.
Used to supply information to the Intrinsic.
This is an indicator to show if this is a new message to be sent, a reply
to the last message read by HPDUserReceive, or is a request to forward
the last message read. Valid values are:
0 Message
1 Reply
2 Forward
3 Reply to All
If a value is not supplied for op_type, HPDUserSend assumes that the
message to be sent is a new message.
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
to the message by HP Desk. 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 HPDUserSend
This Intrinsic may be used after a successful call to HPDUserSignon to
send one message at a time to users on the HP Desk network. Details of
the message are contained in the Transaction File which is identified in
the trans_file parameter. The calling application must have set up the
Transaction File using appropriate transaction records before calling the
Intrinsic.
HPDUserSend may be used to send a new message, or reply to or forward the
last message read by HPDUserReceive. The type of the supplied
Transaction File depends on what HPDUserSend is being asked to do.
For sending a new message or forwarding, the bodytype field of the
tt_body_type transaction must have a value of message, or forms message.
For replying, the field must have a value of reply or forms reply.
If the message is a new message, the Transaction File referenced must
contain at least one recipient name and will normally contain at least
one referenced content file.
If forwarding a message, the new message will take the subject of the
message being forwarded, so a ''tt_subject'' transaction should not be
supplied. The Transaction File must contain at least one recipient name,
to whom the message will be forwarded, and will normally contain at least
one referenced content file. The new message will comprise the content
files referenced in the Transaction File, followed by the original
message.
If replying to a message, HPDUserSend will take the subject, and workout
the Distribution List, from the original message. Therefore neither
subject nor recipient transactions should be supplied in the Transaction
File. As in previous cases, the Transaction File will normally contain
at least one referenced content file.
Messages created by the Intrinsics may be any standard MPE file type
except KSAM and privileged files. Packages and forms packages can be
defined in the message. The construction of the forms package is
described in Chapter 6 (in the examples). If the message is a forms
reply, the forms definition file is taken from the message being replied
to, so the Transaction File should only contain content references to one
or more forms data files.
HPDUserSend can be used to send messages to HP Desk servers, such as the
Distribution List Server and the Remote Directory Updates Server.
The message can be sent to a pre-defined Distribution List by use of
appropriate transaction types. The List Area of the signed on user is
searched first and then the relevant Public Distribution Lists folder.
The files used to construct the message are not deleted once the message
has been successfully sent. It is the responsibility of the application
to deal with this.
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 of the
message.
By including the appropriate transaction records in the Transaction File,
you can set many of the standard HP Desk options on messages sent using
HPDUserSend. These options include security, acknowledgments, urgent or
deferred priority and appointments.
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.
The size of messages sent using HPDUserSend 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.
Broadly speaking, two classes of error can result from a call to
HPDUserSend:
* 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 mailnode 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 analyze the error detail
and take some action, such as informing the sender that the message was
partly or wholly unsuccessful.
[REV BEG]
When HPDUserSend 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, HPDUserSend
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.[REV END]
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 analyze, and act upon,
the result fields in the invalid transactions.
Transaction Records Permitted with HPDUserSend
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 HPDUserSend Intrinsic:
1000 tt_body_type Transaction Body Type Identifier. This
transaction record must be supplied.
2000 tt_eu_info_format Define foreign address format
11100 tt_subject Item subject
11200 tt_msg_priority Message Item Priority Indicator (URGENT or
NORMAL)
11300 tt_security Item Security Indicator (PRIVATE)
11400 tt_ack_level Requested acknowledgment level
11600 tt_mail_time Message Mail Time (deferred mail)
11700 tt_app_date_time Date/time/duration of appointment
11750 tt_todo_date Date of Todo on item
12000 tt_disallow_autof Disallow autoforward indicator
21000 tt_from FROM name and address
21100 tt_to TO name and address. At least one addressee
must be supplied (either a tt_to, tt_cc or
tt_bcc record).
21200 tt_cc CC name and address. At least one addressee
must be supplied (either a tt_to, tt_cc or
tt_bcc record).
21300 tt_bcc BCC name and address. At least one addressee
must be supplied (either a tt_to, tt_cc or
tt_bcc 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. At
least one of these records must be supplied
unless the information is included in a
package.
39000 tt_end_package End Package definition
Session Profile Options Relevant to HPDUserSend
Refer to Chapter 8 for more information on the Session Profile file.
These Session Profile options can be used to change the operation of
HPDUserSend:
100010 sp_accept_fail Acceptable Failure indicator
100100 sp_extra_user_info Define foreign address format
100500 sp_time Interpret times as GMT (rather than local)
format
100800 sp_def_transfile Default Transaction File definition
100900 sp_name_addr_checks Alter name/address checking
Status Returns Specific to HPDUserSend
-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 Application is not signed on as a user
-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
-1006 A dataset is full
-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
-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
-1205 User does not have the capability to use this
Intrinsic
-1900 Unexpected error
-3002 No current message
-3400 Message has no recipients
-3406 The Transaction File is incomplete
-3407 No message has just been received, or it is invalid
-3408 Message is larger than the size allowed
-3409 Start package transaction has no corresponding End
package transaction