Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

## MAIL$MESSAGE_MODIFY

> 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

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

## MAIL$MESSAGE_SELECT

> 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 on or after 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

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

## MAIL$SEND_ABORT

> Cancels a currently executing send operation.

### Format

> MAIL$SEND_ABORT 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 Value Returned.

### Arguments

> #### context

> OpenVMS usage: | context
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_BEGIN.

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

> MAIL$SEND_ABORT is useful when, for example, the user presses Ctrl/C during the execution of MAIL$SEND_MESSSAGE.

### Condition Value Returned

> SS$_NORMAL | Normal successful completion.

## MAIL$SEND_ADD_ADDRESS

> Adds an address to the address list. If an address list does not exist, MAIL$SEND_ADD_ADDRESS creates one.

### Format

> MAIL$SEND_ADD_ADDRESS 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

> Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_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$_SEND_USERNAME

> MAIL$_SEND_USERNAME specifies that the Mail utility add a specified user name to the address list. 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.

> The item code MAIL$_SEND_USERNAME is required.

> #### MAIL$_SEND_USERNAME_TYPE

> MAIL$_SEND_USERNAME_TYPE specifies the type of user name added to the address list. The buffer address field of the item descriptor points to a word that contains the user name type.

> There are two types of user names, as follows:

> - User name specified as a To: address (default)
> - User name specified as a CC: address

> Note Currently, the symbols MAIL$_TO and MAIL$_CC define user name types.

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

> ####

> None.

### Description

> If you do not specify a MAIL$_SEND_USERNAME_TYPE, MAIL$SEND_ADD_ADDRESS uses MAIL$_TO. You can specify only one user name per call to MAIL$SEND_ADD_ADDRESS.

### 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 values returned by LIB$TPARSE.

## MAIL$SEND_ADD_ATTRIBUTE

> Adds an attribute, such as Subject or To, to the message you are currently constructing.

### Format

> MAIL$SEND_ADD_ATTRIBUTE 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

> Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_BEGIN.

> You should specify this argument as 0 in the first of a sequence of calls to MAIL routines. In following calls, you should specify the Send context value returned by the previous routine.

> #### 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$_SEND_CC_LINE

> MAIL$_SEND_CC_LINE specifies a descriptor of the CC: field text. 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$_SEND_FROM_LINE

> MAIL$_SEND_FROM_LINE specifies a descriptor of the From: field text of the message to be sent. 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.

> Calls to MAIL$SEND_ADD_ATTRIBUTE using this input item code should be made before any calls to MAIL$SEND_ADD_ADDRESS.

> The SYSPRV privilege is required to alter the From: of a message.

> #### MAIL$_SEND_SUBJECT

> MAIL$_SEND_SUBJECT specifies a descriptor of the Subject: field text of a message to be sent. 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$_SEND_TO_LINE

> MAIL$_SEND_TO_LINE specifies a descriptor of the To: field text 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.

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

> ####

> None.

### Description

> If you do not specify a To: line, the Mail utility supplies a To: line composed of user names on the To: address list. If you do not specify a CC: line, the Mail utility supplies a CC: line composed of user names on the CC: address list. In either of the above cases, commas separate the user names.

> To add a message's From: field, you must have the SYSPRV privilege, and the Mail DECnet object must have the SYSPRV privilege on OUTGOING CONNECT (users can set the DECnet object privileges at their discretion).

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> 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.

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_042.HTML