SEND / FORWARD A MESSAGE API ICR (10070)

Name

Value

NUMBER

10070

IA #

10070

DATE CREATED

1995/02/19

CUSTODIAL PACKAGE

MAILMAN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XMD

NAME

SEND / FORWARD A MESSAGE API

ORIGINAL NUMBER

10070

GENERAL DESCRIPTION

Contains the following APIs related to creating,
sending, and/or forwarding messages:

^XMD      create, address, and send a message
EN1^XMD   add text to a message, address it, and send it
ENL^XMD   add text to a message
ENT^XMD   interactive create, address, and send a message
ENT1^XMD  forward a message
ENT2^XMD  forward a message and prompt user for more recipients

See the MailMan Programmer Manual, Appendix B, Efficient Use of the API, for
some suggestions on how to efficiently create huge messages used for data
transfer.

I/O variables for the various APIs:

DUZ     (in, optional) User's DUZ.  This is who is actually sending the
message.  If DUZ is not defined, it defaults to the Postmaster (.5).

XMDUZ   (in, optional) User's DUZ or free text.  This is from whom the message
will appear to be.  If it is not defined, it defaults to DUZ.  If it is free
text, it must not be more than 70 characters.

XMSUB   (in) Subject of the message.  Must be from 3 to 65 characters long.
If it is less than 3 characters, then "..." will be appended to it.  If it is
more than 65 characters, it will be truncated.

XMTEXT  (in) The root of the array, in open format, which contains the text of
the message.  The array may be a local or global variable, and it must be in a
format acceptable to FileMan word-processing APIs.

XMSTRIP (in, optional) Characters that should be stripped from the text of the
message.  Default is none.

XMDF    (in, optional) If $D(XMDF), addressing restrictions are waived:
- ignore 'domain closed'
- ignore 'keys required for domain'
- ignore 'may not forward to domain'
- ignore 'may not forward priority mail to mail groups'
- ignore 'message length restrictions to remote addressees'

XMMG    (in, optional) If XMY is not supplied and the process is not queued,
XMMG may be used as the default for the first 'send to:' prompt.
(out) Contains an error message if an error occurs.  Otherwise,
undefined.

XMZ     (in) Message IEN in MESSAGE file (3.9) of message to be forwarded or
altered.
(out) Message IEN in Message file (3.9) of message created/sent.

XMY(    (in) Addressee array.  May contain any of the following:
User's DUZ, or enough of user's name for a positive ID
eg: XMY(1301)="" or XMY("lastname,firs")=""
G.group name (enough for positive ID)
eg: XMY("G.MY GROUP")=""
S.server name (enough for positive ID)
eg: XMY("S.YOUR SERVER OPTION")=""
D.device name (enough for positive ID)
eg: XMY("D.MY PRINTER")=""

You may prefix each addressee (except devices and servers) by:
I: for 'information only' recipient (may not reply)
eg: XMY("I:1301")="" or XMY("I:lastname,firs")=""
C: for 'copy' recipient (not expected to reply)
eg: XMY("C:1301")="" or XMY("C:lastname,firs")=""
L@datetime: for when (in future) to send to this recipient (datetime may be
anything accepted by FileMan)
eg: XMY("L@25 DEC@0500:1301")="" or XMY("L@1 JAN:lastname,firs")=""
or XMY("L@2981225.05:1301")=""
(may combine IL@datetime:  or  CL@datetime:)

To delete recipient, prefix with -
eg: XMY(-1301)="" or XMY("-lastname,firs")=""

Append "@<sitename>" for any addressees at another site:
eg: XMY("I:G.group@site.DNS")=""
or XMY("lastname,firs@site.DNS")=""
or XMY("6102@site.DNS")=""

If the sender (XMDUZ) is a recipient, you may specify the basket in the
sender's mailbox to which the message should be delivered.
eg: XMY(XMDUZ,0)=5 (basket IEN)
or XMY(XMDUZ,0)="MY BASKET" (full basket name)

If SHARED,MAIL is a recipient, you may specify the basket in SHARED,MAIL's
mailbox to which the message should be delivered.
eg: XMY(.6,0)=5 (basket IEN)
or XMY(.6,0)="MY BASKET" (full basket name)

If SHARED,MAIL is a recipient, you may specify the date on which the message
should be deleted from SHARED,MAIL's mailbox,
eg: XMY(.6,"D")=<date> (any date recognized by FileMan)

Sample XMY entries:

XMY("USER,LOCAL")="" Addressed to a local user, whose name is
USER,LOCAL.

XMY("G.MAIL_GROUP)="" Addressed to a local mail group, whose name is in
the MAIL GROUP file.

XMY("LAST,FIRST@domain_name")="" Addressed to a user, at the site named
domain_name.  LAST,FIRST must be in the NEW PERSON file at that site.  If the
local system domain name is domain_name, it will be a local recipient.

XMY("G.MAIL_GROUP@domain_name")="" Addressed to a mail group, at the
site named domain_name.  MAIL_GROUP must be found in the MAIL GROUP file at
that site.

XMY("D.DEVICE@domain_name")="" Addressed to a device, at the site named
domain_name.  DEVICE must be found in the DEVICE file at that site.

XMY("S.OPTION@domain_name")="" Addressed to an option, at the site
named domain_name.  OPTION must be found in the OPTION file at that site.

XMY("INFO:MAIL_GROUP@domain_name")="" Addressed to a mail group at a
remote site.  The message will be delivered "information only" to that group,
meaning that they will not be able to reply to it.

STATUS

Active

XMD

COMPONENT/ENTRY POINT

COMPONENT/ENTRY POINT	COMPONENT DESCRIPTION
XMD	Create and send a new message. If no recipients are defined (in XMY), and '$D(ZTQUEUED), then prompt for them. Addressing restrictions are automatically waived, so there is no need to set XMDF. Compare to SENDMSG^XMXAPI (DBIA 2729). Usage: Set up the input variables D ^XMD Check the output variables More extensive definitions of the I/O variables can be found in the General Description. Core input variables: DUZ (optional) User DUZ. XMDUZ (optional) Message is from other than DUZ. XMSUB Message subject. XMTEXT Message text. XMY (optional) Message addressees. If none, and '$D(ZTQUEUED), the user will be prompted for them. If none, and $D(ZTQUEUED), the message will be created, but it won't be sent, and XMMG will not be defined. Additional input variables: DIFROM (optional) Specifically for FileMan package XMMG (optional) If there are no recipients in XMY, and the job is running in the foreground, XMMG may contain the default recipient presented to the user. If XMMG is not defined, then the default recipient is the user, as defined by XMDUZ. XMROU (optional) Array of routines to be loaded in a PackMan message. For each routine, set XMROU(x)="", where x is the routine name. XMSTRIP (optional) Characters to be removed from the message text Output variables: XMMG This is the variable which the calling program should check to see whether or not the call was successful. If XMMG is undefined, then the call was successful. If the call failed, then XMMG contains the error message. XMZ If the call was successful, then XMZ is the message IEN of the message which was created. If the call failed, then XMZ is unchanged or undefined. Variables killed upon exit: If the call is successful, XMSUB, XMTEXT, XMY, XMSTRIP, XMMG will be killed. If the call fails, those variables may or may not be killed, except for XMMG, which will contain an error message. WARNING: If calling XMD in a Pre-init or Post-init, you MUST NEW DIFROM prior to the call or your message will NOT be delivered.
ENT1	Forward a message. Addressing restrictions are automatically waived, so there is no need to set XMDF. Compare to FWDMSG^XMXAPI (DBIA 2729). Usage: Set up the input variables D ENT1^XMD More extensive definitions of the I/O variables can be found in the General Description. Input variables: DUZ (optional) User DUZ. XMDUZ (optional) Message is forwarded by other than DUZ. XMY Addressees to forward to XMZ Message IEN in MESSAGE file (3.9), of message to forward. Output variables: None. Variables killed upon exit: XMDUZ,XMY
ENT2	Forward a message. If '$D(ZTQUEUED), prompt for additional recipients, whether or not any are already defined. Usage: Set up the input variables D ENT2^XMD More extensive definitions of the I/O variables can be found in the General Description. Input variables: DUZ (optional) User DUZ. XMDUZ (optional) Message is forwarded by other than DUZ. XMDF (optional) If $D(XMDF), all addressing restrictions are waived. XMY (optional) Addressees to forward to. If '$D(ZTQUEUED) (job running in the foreground), the user will be prompted for additional recipients. XMZ Message IEN in MESSAGE file (3.9), of message to forward. Output variables: None. Variables killed upon exit: XMDUZ,XMY
ENT	Place this entry point in an interactive option for the process to send a message. It can be put onto many menus. It is the same as XMSEND, the Send a Message option. It requires that the Entry Action and Exit Action be specified. Set up the option as follows: Entry Action: S XMMENU(0)=<name of the menu option> Routine: ENT^XMD Exit Action: K XMMENU D CHECKOUT^XM Compare to SENDMSG^XMXAPIU (DBIA 2774). Input Variables: DUZ User's DUZ Output Variables: none
ENL	Add text to an existing message. Usage: Set up the input variables D ENL^XMD More extensive definitions of the I/O variables can be found in the General Description. Core input variables: DUZ User DUZ. XMTEXT Message text. XMZ Message IEN in the MESSAGE file (3.9). Additional input variables: XMSTRIP (optional) Characters to be removed from the message text Output variables: none Variables killed upon exit: XMSTRIP
EN1	Add text to a message, and address it and send it. If no recipients are defined (in XMY), and '$D(ZTQUEUED), then prompt the user for them. Usage: Set up the input variables D EN1^XMD More extensive definitions of the I/O variables can be found in the General Description. Core input variables: DUZ User DUZ. XMTEXT Message text. XMY (optional) Message addressees. If none, and '$D(ZTQUEUED), the user will be prompted for them. If none, and $D(ZTQUEUED), the message will be created, but it won't be sent, and XMMG will not be defined. XMZ Message IEN in the MESSAGE file (3.9). Additional input variables: DIFROM (optional) Specifically for FileMan package XMMG (optional) If there are no recipients in XMY, and the job is running in the foreground, XMMG may contain the default recipient presented to the user. If XMMG is not defined, then the default recipient is the user, as defined by DUZ. XMROU (optional) Array of routines to be loaded in a PackMan message. For each routine, set XMROU(x)="", where x is the routine name. XMSTRIP (optional) Characters to be removed from the message text Output variables: none Variables killed upon exit: XMTEXT, XMY, XMSTRIP, XMMG