MESSAGE ACTION API    ICR (2729)

The APIs in this DBIA perform message actions.  They
are designed to be used individually or incorporated into a MailMan front end.

For usage instructions, please refer to the Programmer Manual, available at
the Infrastructure web site.

When used as part of a MailMan front end, INIT^XMVVITAE should be called to
create the MailMan environment in which the user will operate.  Please see
DBIA 2728 for information on the XMVVITAE APIs.

When used individually, from a routine, the XMVVITAE APIs should not be
called.

After every API call, the calling routine should check for the existence of
XMERR.  If any errors occur, the following variables will be defined:
XMERR - the number of errors
^TMP("XMERR",$J,<error number>,"TEXT",<line number>)=<error text>

Parameter definitions:

XMDUZ  User's DUZ or enough of the name for a positive ID.

XMINSTR (optional) Array of special instructions
("ADDR FLAGS")       Special addressing instructions, any or all of the
following:
I  Do not Initialize (kill) the ^TMP addressee global, because it
already contains addressees for this message, as a result of a previous call
to an API.
R  Do not Restrict message addressing:
- Ignore 'domain closed'
- Ignore 'keys required for domain'
- Ignore 'may not forward to domain'
- Ignore 'may not forward priority mail to groups'
- Ignore 'message length restrictions to remote addressees'
X  Do not create the ^TMP addressee global, because addressees are only
being checked for validity.

("FLAGS")    Message is any or all of the following:
P  Priority
I  Information only (may not be replied to)
X  Closed message (may not be forwarded)
C  Confidential message (surrogate may not read)
S  Send to sender (make sender a recipient)
R  Confirm receipt (return receipt requested)

("FROM")     String saying who the message is from (default is user, as
identified by XMDUZ parameter).  This string is placed in field 1 'from' in
the message file.  Must not be any real person, except for Postmaster.  DUZ is
not captured in field 1.1 'sender' of message file, thus making this option
well-suited for messages from VISTA packages.

("FWD BY")   String saying who forwarded the message (default is user, as
identified by XMDUZ parameter).  This string is placed in field 8 'forwarded
by' in the recipient multiple of the message file.  Must not be any real
person, except for Postmaster.  DUZ is not captured in field 8.01 'forwarded
by (xmduz)' in the recipient multiple of message file, thus making this option
well-suited for messages forwarded by VISTA packages.

("HDR")      Print the messages with a header? (0=no; 1=yes) Default is yes.

("LATER")    Date/time (any format understood by FM) on which to send this
message.  Default is now.

("NET REPLY")        Should reply be sent over the network? (0=no; 1=yes)
Default is no.  Currently valid only if sender of original message is remote.

("NET SUBJ") Subject of reply to be sent over the network.  Default is "Re:
<subject of original message>".  Ignored unless XMINSTR("NET REPLY")=1.

("RCPT BSKT")        Basket to deliver to for all recipients.  Default is IN
basket.  Recipients must have specified in their personal preferences that
such targeted basket delivery is allowed.  Otherwise, this option is ignored.

("RECIPS")   Print recipients along with the message?
0  No (default)
1  Print summary recipients
2  Print detailed recipients

("RESPS")    Print which responses?
*  Original message and all responses (default)
0  Original message only
range list (e.g. 0-3,5,7-99) - Print this range of responses.  Ignored
if more than one message is printed.  This parameter is not checked.  It must
be correct.  Range list may also be open-ended (e.g. 1,2,5- means print
responses 1 and 2 and responses 5 to the end).

("SCR KEY")  Scramble key (implies that message should be scrambled).  Must
be 3-20 characters long.

("SCR HINT") Hint for scramble key (mandatory if message is to be
scrambled).  Must be 1-40 characters long.

("SELF BSKT")        Basket to deliver to if sender is recipient.  Default
is IN basket.

("SHARE BSKT")       Basket to deliver to if SHARED,MAIL is recipient.
Default is IN basket.

("SHARE DATE")       Date/time (any format understood by FM) to delete this
message from SHARED,MAIL if SHARED,MAIL is recipient.

("STRIP")    String containing characters to strip from the message text
(XMBODY).  Must be 1-20 characters long.

("TO PROMPT")        During interactive message addressing, contains the
suggested initial addressee.  Default is the user identified by XMDUZ.

("TYPE")     Message type is one of the following special types:
D  Document
S  Spooled Document
X  DIFROM
O  ODIF
B  BLOB (reserved for future use)
K  KIDS

("VAPOR")    Date/time (any format understood by FM) on which to delete
(vaporize) this message from recipient baskets.  Recipients may override this
date.  Also used to set vaporize date/time for messages already in one's own
baskets.

("WHEN")     Date/time (any format understood by FM) on which to print
messages.  Default is now.

[.]XMTO        Addressee or addressee array (if array, must be passed by
reference).  May be or contain any of the following:
User's DUZ, or enough of user's name for a positive ID
eg: 1301 or "lastname,firs" or ARRAY(1301)=""
ARRAY("lastname,firs")=""
G.group name (enough for positive ID)
S.server name (enough for positive ID)
D.device name (enough for positive ID)
You may prefix each addressee (except devices and servers) by:
I: for 'information only' recipient (may not reply)
eg: "I:1301" or "I:lastname,firs"
C: for 'copy' recipient (not expected to reply)
eg: "C:1301" or "C:lastname,firs"
L@datetime: for when (in future) to send to this recipient (datetime may be
anything accepted by FM)
eg: "L@25 DEC@0500:1301" or "L@1 JAN:lastname,firs"
or "L@2981225.05:1301"
(may combine IL@datetime:  or  CL@datetime:)
To delete recipient, prefix with -
eg: -1301 or "-lastname,firs"
Append "@<sitename>" for any addressees at another site:
eg: "I:G.group@site.dsn" or "LAST,FIRST@site.dsn"

XMK and XMKZ for APIs which act on one message:
XMK  (optional, depending on XMKZ) Basket (IEN or name) containing the
message.
XMKZ  Identifies the message.  Must be one of the following:
Message number (XMZ) in Message global (XMK must not be specified)
Message number in the basket (XMK must be specified)

XMK and XMKZA for APIs which act on groups of messages:
XMK  (optional, depending on XMKZA) Basket (IEN or name) containing the
messages.
XMKZA        Identifies messages, using a list or list array, which may end
in a comma.  Must be one of the following:
Message numbers (XMZ) in Message global (XMK must not be specified, AND
ranges are not allowed):
- List: "1234567" or "1234567,9763213"
- List array:   ARRAY(1234567)=""
ARRAY(9763213)=""
Message numbers in the basket (XMK must be specified, ranges are OK):
- List: "1" or "1,3,5-7"
- List array:   ARRAY("1,3")=""
ARRAY("5-7")=""