Document revision date: 30 March 2001

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

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_041.HTML