Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

## MAIL$SEND_ADD_BODYPART

> Builds the body of a message.

### Format

> MAIL$SEND_ADD_BODYPART 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.

> See MAIL$SEND_BEGIN for a description of an input item descriptor.

### Input Item Codes

> #### MAIL$_SEND_DEFAULT_NAME

> MAIL$_SEND_DEFAULT_NAME specifies the default file specification of a text file to be opened. 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_FID

> MAIL$_SEND_FID specifies the file identifier of the text file to be opened. The buffer address field of the item descriptor points to a buffer that contains the file identifier. To identify a file using a file identifier, you must also specify the device identifier for the file. Specify the device identifier using the MAIL$_SEND_DEFAULT_NAME item code. More information about using a file ID for specifying files can be found in OpenVMS Record Management Services Reference Manual. Note that the MAIL$_SEND_FID item code and the MAIL$_SEND_FILENAME item code are mutually exclusive.

> #### MAIL$_SEND_FILENAME

> MAIL$_SEND_FILENAME specifies the input file specification of the text file to be opened. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 255 characters long. Note that the MAIL$_SEND_FILENAME item code and the MAIL$_SEND_FID item code are mutually exclusive.

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

> #### MAIL$_SEND_RECORD

> MAIL$_SEND_RECORD specifies a descriptor of a text record to be added to the body 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.

> When creating a message, do not specify MAIL$_SEND_RECORD in the same call (or series of calls) to MAIL$SEND_ADD_BODYPART with the following item codes:

> - MAIL$_SEND_FID
> - MAIL$_SEND_FILENAME

Note Do not use the MAIL$_SEND_RECORD item code with the MAIL$SEND_ADD_BODYPART routine called from a detached process. The routine creates a temporary file in SYS$SCRATCH that is inaccessible to the detached process.

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

> When you specify MAIL$_SEND_RESULTSPEC, MAIL$SEND_ADD_BODYPART returns the resultant file specification identified with MAIL$_SEND_FILENAME. 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

> You can use MAIL$SEND_ADD_BODYPART to specify a file that contains the entire message or to add a single record to a message. If the message is contained in a file, you call MAIL$SEND_ADD_BODYPART once, specifying the file name. If you want to add to the message record-by-record, you can call MAIL$SEND_ADD_BODYPART repeatedly, specifying a different record each time until you complete the message.

> You cannot specify both a file name and a record for the same message. You can specify either MAIL$_SEND_FILENAME or MAIL$_SEND_FID once, or you can specify MAIL$_SEND_RECORD one or more times.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> MAIL$_CONITMCOD | The specified item codes define conflicting operations.
> MAIL$_INVITMCOD | The specified item code is invalid.
> MAIL$_INVITMLEN | The specified item length is invalid.
> MAIL$_MISREQITEM | The required item is missing.
> MAIL$_OPENIN | The required file is missing.
> SS$_ACCVIO | Access violation.

## MAIL$SEND_BEGIN

> Initiates processing to send a message to the users on the address list. You must call MAIL$SEND_BEGIN before you call any other send routine.

### Format

> MAIL$SEND_BEGIN 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 other send routines. The context argument is the address of a longword that contains send context information.

> You should specify the value of this argument as 0 in the first of a sequence of calls to send routines. In subsequent calls, you should specify the send context value returned by this 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_PERS_NAME
> MAIL$_SEND_NO_PERS_NAME

> Note that you must specify only one of these item codes. An error is generated if you specify both item codes. MAIL$_SEND_PERS_NAME specifies the personal name text to be used in the message header. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 127 characters long.

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

> The Boolean item code MAIL$_SEND_NO_PERS_NAME specifies that no personal name string be used during message construction.

> Specify the value 0 in the buffer length and buffer address fields of the item descriptor.

> #### MAIL$_SEND_SIGFILE
> MAIL$_SEND_NO_SIGFILE

> Note that you must specify only one of these item codes. An error is generated if you specify both item codes. MAIL$_SEND_SIGFILE specifies the full OpenVMS file specification of the signature file to be used in the message. The default file specification used for a signature file is the user mail directory specification and .SIG as the file type. 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.

> The Boolean item code MAIL$_SEND_NO_SIGFILE specifies that no signature file be used during message construction.

> Specify the value 0 in the buffer length and buffer address fields 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

> #### MAIL$_SEND_COPY_FORWARD

> When you specify the Boolean item code MAIL$_SEND_COPY_FORWARD, MAIL$SEND_BEGIN returns the value of the caller's copy forward flag as a longword value.

> #### MAIL$_SEND_COPY_SEND

> When you specify the Boolean item code MAIL$_SEND_COPY_SEND, MAIL$SEND_BEGIN returns the value of the caller's copy send flag as a longword value.

> #### MAIL$_SEND_COPY_REPLY

> When you specify the Boolean item code MAIL$_SEND_COPY_REPLY, MAIL$SEND_BEGIN returns the value of the caller's copy reply flag as a longword value.

> #### MAIL$_SEND_USER

> When you specify MAIL$_SEND_USER, MAIL$SEND_BEGIN returns the process owner's user name. 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$SEND_BEGIN creates and initializes a send context for subsequent calls to send routines.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> MAIL$_CODERR | Internal system error.
> MAIL$_CONITMCOD | The specified item codes perform conflicting operations.
> MAIL$_ILLPERNAME | The specified personal name string 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.
> SS$_ACCVIO | Access violation.
> Any condition values returned by $GETJPIW, LIB$FREE_VM, and LIB$GET_VM.

## MAIL$SEND_END

> Terminates send processing.

### Format

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

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

> If send processing is successfully terminated, the value of the context argument 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$SEND_END routine deallocates the send context as well as any dynamic memory allocated by previous send routine calls.

### 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.
> Any condition value returned by LIB$FREE_VM.

## MAIL$SEND_MESSAGE

> Begins the actual sending of the message after the message has been constructed.

### Format

> MAIL$SEND_MESSAGE 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_ERROR_ENTRY

> MAIL$_SEND_ERROR_ENTRY specifies the longword address of an entry point to process errors during a send operation. The descriptor of the recipient that failed, the address of the signal array, and the user-specified data are passed as input to the routine. Refer to the OpenVMS Programming Concepts Manual for more information about the signal array and its use by condition-handling routines.

> #### MAIL$_SEND_SUCCESS_ENTRY

> MAIL$_SEND_SUCCESS_ENTRY specifies the longword address of an entry point to process successes during a send operation. The descriptor of the recipient that succeeded, the address of the signal array, and the user-specified data are passed as input to the routine. Refer to the OpenVMS Programming Concepts Manual for more information about the signal array and its use by condition-handling routines.

> #### MAIL$_SEND_USER_DATA

> MAIL$_SEND_USER_DATA specifies a longword that MAIL$SEND_MESSAGE passes to the SEND action routines.

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

> The MAIL$SEND_MESSAGE routine sends a message built with the MAIL$SEND_ADD_BODYPART routine to every user on the address list. If you have not used MAIL$SEND_ADD_BODYPART to construct a message, MAIL$SEND_MESSAGE sends only a message header.

> If MAIL$SEND_MESSAGE encounters errors sending to an addressee, it calls the routine specified by MAIL$_SEND_ERROR_ENTRY. Otherwise, it calls the routine specified by MAIL$_SEND_SUCCESS_ENTRY.

> If either routine is not specified, MAIL$SEND_MESSAGE calls no other 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 $CONNECT.

## MAIL$USER_BEGIN

> Initiates access to the Mail common user database. You must call MAIL$USER_BEGIN before you call any other user routines.

### Format

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

> User context information to be passed to other user routines. The context argument is the address of a longword that contains user context information.

> You should specify the value of this argument as 0 in the first of a sequence of calls to MAIL routines. In following calls, you should specify the user 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. 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. 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$_USER_AUTO_PURGE

> When you specify the Boolean item code MAIL$_USER_AUTO_PURGE, MAIL$USER_BEGIN returns the value of the automatic purge mail flag as a longword value.

> #### MAIL$_USER_CAPTIVE

> When you specify the Boolean item code MAIL$_USER_CAPTIVE, MAIL$USER_BEGIN returns the value of the UAF CAPTIVE flag as a longword value.

> #### MAIL$_USER_CC_PROMPT

> When you specify the Boolean item code MAIL$_USER_CC_PROMPT, MAIL$USER_BEGIN returns the value of the cc prompt flag as a longword value.

> #### MAIL$_USER_COPY_FORWARD

> When you specify the Boolean item code MAIL$_USER_COPY_FORWARD, MAIL$USER_BEGIN returns the value of the copy self forward flag as a longword value.

> #### MAIL$_USER_COPY_REPLY

> When you specify the Boolean item code MAIL$_USER_COPY_REPLY, MAIL$USER_BEGIN returns the value of the copy self reply flag as a longword value.

> #### MAIL$_USER_COPY_SEND

> When you specify the Boolean item code MAIL$_USER_COPY_SEND, MAIL$USER_BEGIN returns the value of the copy self send flag as a longword value.

> #### MAIL$_USER_FORWARDING

> When you specify MAIL$_USER_FORWARDING, MAIL$USER_BEGIN returns the forwarding address 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$_USER_FORM

> When you specify MAIL$_USER_FORM, MAIL$USER_BEGIN returns the default print form 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$_USER_FULL_DIRECTORY

> When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_BEGIN returns complete directory path of the MAIL subdirectory. 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$_USER_NEW_MESSAGES

> When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_BEGIN returns the new message count. The buffer address field of the item descriptor points to a word that receives the new message count.

> #### MAIL$_USER_PERSONAL_NAME

> When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_BEGIN returns the personal name string. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 127 characters long.

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

> #### MAIL$_USER_QUEUE

> When you specify MAIL$_USER_QUEUE, MAIL$USER_BEGIN returns the default print queue name. 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$_USER_RETURN_USERNAME

> When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_BEGIN returns the user name 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$_USER_SIGFILE

> When you specify MAIL$_USER_SIGFILE, MAIL$USER_BEGIN returns the default signature file specification. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 255 characters long.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 4493PRO_043.HTML