Retrieves a message from the set of currently selected messages.
Format
MAIL$MESSAGE_GET context ,in_item_list ,out_item_list
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. All utility routines return a condition
value in R0. Condition values that can be returned by this
routine are listed under Condition Values Returned.
2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Message context information to be passed to message routines.
The context argument is the address of a longword that contains
message context information returned by MAIL$MESSAGE_BEGIN.
in_item_list
OpenVMS usage:itmlst_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying options for the routine. The in_item_list
argument is the address of a list of item descriptors, each of
which specifies an option and provides the information needed to
perform the operation.
The item list is terminated by longword value of 0.
3 – Input Item Codes
MAIL$_MESSAGE_AUTO_NEWMAIL
When you specify the Boolean item code MAIL$_MESSAGE_AUTO_
NEWMAIL, MAIL$MESSAGE_GET automatically places a new message
in the mail folder as it is read. MAIL$_MESSAGE_AUTO_NEWMAIL
is valid only when specified with the item code MAIL$_MESSAGE_
CONTINUE.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_MESSAGE_BACK
When you specify the Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_GET reads the message identification number of a
specified message to return the first record of the preceding
message.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_CONTINUE
When you specify the Boolean item code MAIL$_MESSAGE_CONTINUE,
MAIL$MESSAGE_GET reads the message identification number of a
specified message to return the next text record of the current
message.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_ID
MAIL$_MESSAGE_ID specifies the message identification number of
a message on which an operation is to be performed. The buffer
address field of the item descriptor points to a longword that
contains the message identification number.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_NEXT
When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_GET reads the message identification number of
a specified message to return the first record of the message
following the current message.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
out_item_list
OpenVMS usage:itmlst_3
type: longword
access: write only
mechanism: by reference
Item list specifying the information you want the routine to
return. The out_item_list argument is the address of a list of
item descriptors, each of which describes an item of information.
The list of item descriptors is terminated by longword value of
0.
4 – Output Item Codes
MAIL$_MESSAGE_BINARY_DATE
When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_GET
returns the message arrival date as a quadword binary value.
MAIL$_MESSAGE_CC
When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_GET returns the
CC: field of the current message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_CURRENT_ID
When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_GET
returns the message identification number of the current message.
The buffer address field of the item descriptor points to a
longword that receives the message identifier number.
MAIL$_MESSAGE_DATE
When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_GET returns
the message creation date string. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_EXTID
MAIL$_MESSAGE_EXTID specifies the external message identification
number of the current message. The buffer address field of the
item descriptor points to a buffer that contains a character
string 0 to 255 characters long.
MAIL$_MESSAGE_FROM
When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_GET returns the
From: field of the specified message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_RECORD
When you specify MAIL$_MESSAGE_RECORD, MAIL$MESSAGE_GET returns
a record of the message. The buffer address field of the item
descriptor points to a buffer that receives a character string 0
to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_RECORD is valid only when specified with the item
code MAIL$_MESSAGE_CONTINUE.
Do not specify MAIL$_MESSAGE_RECORD with the following item
codes:
o MAIL$_MESSAGE_BACK
o MAIL$_MESSAGE_ID
o MAIL$_MESSAGE_NEXT
MAIL$_MESSAGE_RECORD_TYPE
When you specify MAIL$_MESSAGE_RECORD_TYPE, MAIL$MESSAGE_
GET returns the record type. A record may be either header
information (MAIL$_MESSAGE_HEADER) or text (MAIL$_MESSAGE_TEXT).
The buffer address field of the item descriptor points to a word
that receives the record type.
MAIL$_MESSAGE_RETURN_FLAGS
When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_GET
returns the Mail system flag for the current message as a 2-byte
bit mask value.
MAIL$_MESSAGE_SENDER
When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_GET returns
the name of the sender of the current message. The buffer address
field of the item descriptor points to a buffer that receives a
character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_SIZE
When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_GET returns the
size in records of the current message as a longword value.
MAIL$_MESSAGE_SUBJECT
When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_GET returns
the Subject: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a
character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_TO
When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_GET returns the
To: field of the specified message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
5 – Description
The first time the MAIL$MESSAGE_GET routine is called, the
message information is returned for the first requested message,
and the status returned is MAIL$_MSGINFO. Subsequent calls to
MAIL$MESSAGE_GET with the MAIL$_MESSAGE_CONTINUE item code return
the message text records with the status MAIL$_MSGTEXT, until no
more records are left, when MAIL$_NOMOREREC is returned.
6 – Condition Values Returned
MAIL$_MSGINFO Informational records are successfully
returned.
MAIL$_MSGTEXT Text record is successfully returned.
MAIL$_ILLCTXADR The context block address is illegal.
MAIL$_INVITMCOD The specified item code is invalid.
MAIL$_INVITMLEN The specified item length is invalid.
MAIL$_MISREQITEM The required item is missing.
MAIL$_NOFILEOPEN The mail file is not open.
MAIL$_NOMOREREC No more records can be found.
MAIL$_NOTREADIN The operation is invalid; you are not reading
a message.
MAIL$_RECTOBIG The record is too large for the mail buffer.
MAIL$_WRONGCTX The context block is incorrect.
MAIL$_WRONGFILE The specified file is incorrect in this
context.
SS$_ACCVIO Access violation.
Any condition value returned by $FIND and $UPDATE.