MESSAGE INFO API ICR (1144)

Name

Value

NUMBER

1144

IA #

1144

DATE CREATED

1995/02/20

CUSTODIAL PACKAGE

MAILMAN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XMGAPI2

NAME

MESSAGE INFO API

GENERAL DESCRIPTION

This API contains the following function:

$$HDR^XMGAPI2 - retrieve information about a message.

STATUS

Active

XMGAPI2

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$HDR

This function retrieves message header information,
as well as other information about a message.  How much information is
returned depends on the value of FLAG, one of the parameters.

If successful, it sets up (in ARRAY, which must be passed by reference) an
array of information about a message, and returns zero (0).

If unsuccessful, returns one of the following:
"1-Undefined message number"
"1-No message number"
"1-No such message"
"2-User is not a sender of recipient."
"4-Invalid user"

Compare to $$NET^XMRENT (DBIA 1143), and INMSG^XMXUTIL2 and all other APIs in
^XMXUTIL2 (DBIA 2736).

Usage: S X=$$HDR^XMGAPI2(XMZ,.ARRAY,FLAG)

Examples:
---------------------------------------------------------------

Example of specifying an non-existent message:

S X=$$HDR^XMGAPI2(999,.VAR,"")
I +X>0 W !,X
"1-No such message"

Note that VAR is UNCHANGED from state prior to call if function value is
greater than zero.
--------------------------------------------------------------

USING A FLAG OF ZERO

Example of a Message from a Local User:

S DATA=$$HDR^XMGAPI2(123456,.VAR,0)

Data will be returned as 0, if 123456 is a valid message.  Array will be
returned as:

VAR("BROADCAST") = 0
VAR("BSKT")      = "IN"
VAR("BSKT IEN")  = 1
VAR("DATE")      = "SEPTEMBER 10, 1993@09:00:00"
VAR("DATE FM")   = 2930910.9
VAR("LINES")     = 22
VAR("NEW")       = 1
VAR("PXMZ")      = ""
VAR("SENDER")    = "USER,JOE"
VAR("SENDER DUZ")= 77
VAR("SUBJ")      = "HELLO!"
VAR("SURROG")    = ""
VAR("TYPE")      = "P"
VAR("XMZ")       = 123456


Example of Message from a Remote User:

S DATA=$$HDR^XMGAPI2(123457,.VAR,0)

Data and the array information for message 123457 will be returned as above
for message 123456.  The remote user will be returned as a string.

VAR("SENDER")    = "JEAN247@domainname.FR"
VAR("SENDER DUZ")= ""


Example of a Response from a Local User:

DATA=$$HDR^XMGAPI2(123458,.VAR,0)

Data and the array information for message 123458 will be returned as above
for message 123456.  The value of the pointer to the message will be returned
as below:

VAR("PXMZ")  = 123456
VAR("SUBJ")  = "Re: HELLO!"
VAR("XMZ")   = 123458


Example of a Response from a Remote User:

S DATA=$$HDR^XMGAPI2(123459,.VAR,0)

Data and the array information for message 123459 will be returned as above
for message 123458.  The remote user will be returned as a string.

VAR("PXMZ")      = 123456
VAR("SENDER")    = "JEAN247@domainname.FR"
VAR("SENDER DUZ")= ""
VAR("SUBJ")      = "Re: HELLO!"
VAR("XMZ")       = 123459
----------------------------------------------------------------------

USING A FLAG OF 1

Example of Message from a Local User:

S DATA=$$HDR^XMGAPI2(123456,.VAR,1)

Data and the array information for message 123456 will be returned as above.
In addition, the following will be returned in the VAR array:

VAR("RRED")      = 2  Responses Read
VAR("RRCV")      = 3  Responses Received
VAR("BLOBCNT")   = 0  Non-textual body parts attached.
--------------------------------------------------------------------

USING A FLAG OF 91

Example of a Message from a Local User:

S DATA=$$HDR^XMGAPI2(123456,.VAR,91)

Data and the array information for message 123456 will be returned as above.
In addition, the following will be returned in the VAR array.  Each node is a
response number and each value is a pointer to File #3.9.

VAR("RSP",1)=123458
VAR("RSP",2)=123459
VAR("RSP",3)=123501
--------------------------------------------------------------------------

USING A FLAG OF 92

Example of a Message from a Local User:

S DATA=$$HDR^XMGAPI2(123456,.VAR,92)

Data and the array information for message 123456 will be returned as with
Flag 1.  In addition, the following will be returned the VAR array.  (Each
node is an image counter and each value is a pointer to the Object file
(#2005), A Binary Large OBject - BLOB).

VAR("BLOB",1)=100
VAR("BLOB",2)=3345
VAR("BLOB",3)=14445
--------------------------------------------------------------------------

USING A FLAG OF  93

Example of a Message from a Local User:

S DATA=$$HDR^XMGAPI2(123456,.VAR,93)

Data and the array information for message 123456 will be returned as with
Flag 91.  In addition, the array of image counter and values will be returned
as above.

VARIABLES	TYPE	VARIABLES DESCRIPTION
DUZ	Input	User's DUZ. The IEN of the user in the NEW PERSON file (200).
XMDUZ	Used	The user's DUZ. Default is DUZ. This is the user, in relation to whom, some of the message information will be obtained.
XMZ	Input	IEN of the message in the MESSAGE file (3.9) about which information is to be obtained.
FLAG	Used	Determines what information is obtained about the message. Possible values are: 0 - return basic information (default) 1 - return basic information + response and BLOB count information 91 - return flag 1 information + response IDs 92 - return flag 1 information + BLOB IDs 93 - return all of the above
ARRAY	Output	Array of information. If FLAG=0 or undefined: ("BROADCAST") = 1 if the message was broadcast; 0 otherwise ("BSKT") basket name (XMDUZ); null if not in basket ("BSKT IEN") basket IEN (XMDUZ); null if not in basket ("DATE") message date/time, in format MAY 25, 1999@08:16:00, if local, or as sent, if remote. ("DATE FM") message date/time (FileMan format); date only, if remote. ("LINES") number of lines in the original message ("NEW") = 1 if the message is new; 0 otherwise ("PXMZ") message number of original message; null if not a response ("SENDER") sender (from) (external format) ("SENDER DUZ") sender (from) DUZ; null if remote or fictitious ("SUBJ") subject (external format) ("SURROG") surrogate sender (external format) ("TYPE") message type (piece 7 of the message's zero node) ("XMZ") message IEN in message file If FLAG=1, returns value array as with flag 0, and additional value array as follows: ("RRED") responses read (XMDUZ); null if not applicable ("RRCV") responses received; null if not applicable ("BLOBCNT") (specific to Imaging pkg) number of non-textual body parts attached If FLAG=91, and if the message has responses, returns value array as with flag 1, and an array of response nodes and values as follows: ("RSP",i) (pointer to 3.9 file) array of responses, where i is the response number If FLAG=92, and if the message has BLOBs, returns value array as with flag 1, and an array of non-textual body parts as follows: ("BLOB",i) (specific to Imaging pkg) (pointer to 2005 file) array of BLOBS If FLAG=93, returns all of the above.