CREATE A MESSAGE STUB API ICR (10066)

Name

Value

NUMBER

10066

IA #

10066

DATE CREATED

1994/11/02

CUSTODIAL PACKAGE

MAILMAN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XMA2

NAME

CREATE A MESSAGE STUB API

ORIGINAL NUMBER

10066

GENERAL DESCRIPTION

The API in this routine is the first step in sending a
message, when the message text will be loaded directly into the mail global by
the calling application (rather than being copied from a temporary "build
site" as with ^XMD).

This first step is to create a message stub, which is an entry in the Message
file (3.9), with no text or recipients.

The next step is to add the text into the text field of the message (DBIA
10113).

Optionally, the next step is to set any special handling fields:
S DIE=3.9,DA=XMZ,DR="<field #>////<value>" D ^DIE

Field #   Value   Causes message to be
-------   -----   --------------------
1.7         P       Priority
1.95        y       Closed
1.96        y       Confidential
1.97        y       Information only

Example:  To force message 100213 to be priority and closed:
S DIE=3.9,DA=100213,DR="1.7////P;1.95////y" D ^DIE

The final step is to address and send the message, using ENT1^XMD or ENT2^XMD
(DBIA 10070).

STATUS

Active

XMA2

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

GET

This entry point should not be used.  Use XMZ^XMA2,
instead.

GET^XMA2 functions exactly like XMZ^XMA2, except for one thing.  If it fails,
it causes the application to halt.

XMZ

Create a new message stub in the Message file 3.9.

The SUBJECT field (.01) will be set to XMSUB.  The FROM field (1) will be set
to XMDUZ. The SENT DATE/TIME field (1.4) will be set to the current date/time,
in internal FileMan format.  If XMDUZ is a number, and it differs from DUZ,
then the SENDER field (1.1) will be set to DUZ.  If XMDUZ=.5 and DUZ'=.5, the
INFORMATION ONLY? field (1.97) will be set to 'y', thus making the stub
'information only'.

Compare to CRE8XMZ^XMXAPI (DBIA 2729).

Usage: D XMZ^XMA2 I XMZ=-1 D error routine

Note that it is important to check XMZ after the call.  If it equals -1, the
call has failed.

VARIABLES	TYPE	VARIABLES DESCRIPTION
XMSUB	Input	The subject of the message. It is placed in the SUBJECT field (.01) of the message stub. If it is more than 65 characters, it is truncated to 65 characters. If it is less than 3 characters, "..." is appended to it. Leading and trailing blanks are removed. Any sequence of 3 or more blanks is reduced to 2. Any control characters are removed. Any up-arrows ("^") are encoded as "~U~". It may not pattern match 1"R"1.N, or else the call will fail, and XMZ will be set to -1.
XMDUZ	Used	(optional) This is who the message is from. It will be placed in the FROM field (1) of the message stub. It may be any of the following: - If zero, null, or not defined, it defaults to DUZ. - The DUZ of the person the message is "From". If not the same value as DUZ, the person indicated by DUZ (the surrogate) will be captured in the SENDER field (1.1). - A string from 1 to 70 characters long indicating a ficticious "from", such as "PACKAGE XYZ". (DUZ will NOT be captured in the SENDER field.)
XMZ	Output	Message IEN in the Message file 3.9, of the new message stub. If the call fails (usually because it can't get a lock on the Message file), XMZ will be set to -1.
DUZ	Used	The IEN in the NEW PERSON file (200) of the person actually creating the message stub. If null or zero or not defined, it defaults to the Postmaster (.5).