 |
OpenVMS Utility Routines Manual
MAIL$MESSAGE_END
Ends message processing.
Format
MAIL$MESSAGE_END context ,in_item_list ,out_item_list
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.
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. If
message processing ends successfully, the argument
context is changed to 0.
in_item_list
| OpenVMS usage: |
itmlst_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying options for the routine. This routine does not use
the in_item_list argument.
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.
This routine does not use the out_item_list argument.
Description
The MAIL$MESSAGE_END routine deallocates the message context created by
MAIL$MESSAGE_BEGIN as well as any dynamic memory allocated by other
message routines.
Condition Values Returned
|
MAIL$_INVITMCOD
|
The specified item code is invalid.
|
|
MAIL$_INVITMLEN
|
The specified item length is invalid.
|
|
MAIL$_MISREQITEM
|
The required item is missing.
|
|
SS$_ACCVIO
|
Access violation.
|
|
Any condition value returned by LIB$FREE_VM.
|
MAIL$MESSAGE_GET
Retrieves a message from the set of currently selected messages.
Format
MAIL$MESSAGE_GET context ,in_item_list ,out_item_list
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.
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.
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.
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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 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:
- MAIL$_MESSAGE_BACK
- MAIL$_MESSAGE_ID
- 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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 in the buffer
length field of the item descriptor.
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.
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.
|
MAIL$MESSAGE_INFO
Obtains information about a specified message contained in the set of
currently selected messages.
Format
MAIL$MESSAGE_INFO context ,in_item_list ,out_item_list
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.
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.
Input Item Codes
MAIL$_MESSAGE_BACK
When you specify Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_INFO reads the identification number of the current
message and returns the preceding message.
Specify the value 0 in the buffer length and
buffer address fields of the item descriptor.
Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO.
MAIL$_MESSAGE_ID
MAIL$_MESSAGE_ID specifies the message identification number of the
message on which the 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 MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO.
MAIL$_MESSAGE_NEXT
When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_INFO reads the message identification number of the
current message and returns the message that follows it.
Specify the value 0 in the buffer length and
buffer address fields of the item descriptor.
Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO.
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.
Output Item Codes
MAIL$_MESSAGE_BINARY_DATE
When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_INFO returns
the message arrival date as a quadword binary value.
MAIL$_MESSAGE_CC
When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_INFO 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 255 characters long.
Specify a value from 0 to 255 in the buffer
length field of the item descriptor.
MAIL$_MESSAGE_CURRENT_ID
When you specify MAIL$_MESSAGE_ID, MAIL$MESSAGE_INFO 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 identification number of the
current message.
MAIL$_MESSAGE_DATE
When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_INFO 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
When you specify MAIL$_MESSAGE_EXTID, MAIL$MESSAGE_INFO returns the
external identification number of the current message as a 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_FROM
When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_INFO 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 255 characters long.
Specify a value from 0 to 255 in the buffer
length field of the item descriptor.
MAIL$_MESSAGE_REPLY_PATH
When you specify MAIL$_MESSAGE_REPLY_PATH, MAIL$MESSAGE_INFO returns
the reply path of the specified message. 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_RETURN_FLAGS
When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_INFO returns
the Mail system flag values for the current message as a 2-byte bit
mask value.
MAIL$_MESSAGE_SENDER
When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_INFO 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 255 characters long.
Specify a value from 0 to 255 in the buffer
length field of the item descriptor.
MAIL$_MESSAGE_SIZE
When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_INFO returns the size
of the current message in records as a longword value.
MAIL$_MESSAGE_SUBJECT
When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_INFO 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 255 characters long.
Specify a value from 0 to 255 in the buffer
length field of the item descriptor.
MAIL$_MESSAGE_TO
When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_INFO 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 255 characters long.
Specify a value from 0 to 255 in the buffer
length field of the item descriptor.
Description
MAIL$MESSAGE_INFO obtains information about a particular message.
MAIL$MESSAGE_GET retrieves a message from the set of currently selected
messages.
The first call to MAIL$MESSAGE_GET passes control to MAIL$MESSAGE_INFO.
Subsequent calls that include the MAIL$_MESSAGE_CONTINUE item code
return text records.
Condition Values Returned
|
MAIL$_CONITMCOD
|
The specified item codes define conflicting operations.
|
|
MAIL$_DELMSG
|
The message is deleted.
|
|
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$_NOMOREMSG
|
No more messages.
|
|
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 LIB$GET_VM.
|
|
