Updated: 11 December 1998

OpenVMS Utility Routines Manual

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

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.

Modifies information in the message header.

Format

MAIL$MESSAGE_MODIFY 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 the Boolean item code MAIL$_MESSAGE_BACK, MAIL$MESSAGE_MODIFY reads the identification number of the specified message in order to return the first record in 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_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_MODIFY.

MAIL$_MESSAGE_FLAGS

MAIL$_MESSAGE_FLAGS specifies system flags for new mail. The buffer address field of the item descriptor points to a word that contains bit mask offsets. The following offsets can be used to modify the 2-byte bit mask:

• MAIL$V_replied
• MAIL$V_marked

MAIL$_MESSAGE_ID

MAIL$_MESSAGE_ID specifies the message identification number of the 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_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_MODIFY.

MAIL$_MESSAGE_NEXT

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, MAIL$MESSAGE_MODIFY reads the message identification number of a message and returns the first record in 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_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_MODIFY.

out_item_list

Output Item Code

MAIL$_MESSAGE_CURRENT_ID

When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_MODIFY 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.

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 $FIND and $UPDATE.

Selects a message or messages from the currently open mail file. Before you attempt to read a message, you must select it.

Format

MAIL$MESSAGE_SELECT 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_BEFORE

When you specify MAIL$_MESSAGE_BEFORE, MAIL$MESSAGE_SELECT selects a message received before a specified date and time. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 255 characters long in absolute time.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

MAIL$_MESSAGE_CC_SUBSTRING

MAIL$_MESSAGE_CC_SUBSTRING specifies a character string that must match a substring contained in the CC: field of the specified message. If the strings match, the message is selected. 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_FLAGS

MAIL$_MESSAGE_FLAGS specifies bit masks that must be initialized to 1.

MAIL$_MESSAGE_FLAGS_MBZ

MAIL$_MESSAGE_FLAGS_MBZ specifies Mail system flags that must be set to 0.

MAIL$_MESSAGE_FOLDER

MAIL$_MESSAGE_FOLDER specifies the name of the folder that contains messages to be selected.

The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

This item code is required.

MAIL$_MESSAGE_FROM_SUBSTRING

MAIL$_MESSAGE_FROM_SUBSTRING specifies a user-specified character string that must match the substring contained in the From: field of a specified message. If the strings match, the message is selected.

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_SINCE

When you specify MAIL$_MESSAGE_SINCE, the Mail utility selects a message received since a specified date and time.

The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 255 characters long in absolute time.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

MAIL$_MESSAGE_TO_SUBSTRING

MAIL$_MESSAGE_TO_SUBSTRING specifies a user-specified character string that must match a substring contained in the To: field of a specified message. If the strings match, the message is selected.

The buffer address field of the item descriptor points to a buffer that contains 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_SUBJ_SUBSTRING

MAIL$_MESSAGE_SUBJ_SUBSTRING specifies a user-specified character string that must match a substring contained in the Subject: field of a specified message. If the strings match, the message is selected.

The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

out_item_list

Output Item Code

MAIL$_MESSAGE_SELECTED

When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_SELECT returns the number of selected messages as a longword value.

Description

MAIL$MESSAGE_SELECT deselects previously selected messages whether or not you request a valid selection.

Condition Values 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$_INVQUAVAL	The specified qualifier is invalid
MAIL$_MISREQITEM	The required item is missing.
MAIL$_NOFILEOPEN	The mail file is not open.
MAIL$_NOTEXIST	The specified folder does not exist.
MAIL$_NOTISAM	The operation applies only to indexed files.
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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4493PRO_036.HTML