HP OpenVMS Utility Routines Manual
Previous Contents Index

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_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.

Previous Next Contents Index