Updated: 11 December 1998

OpenVMS Utility Routines Manual

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.

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

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.

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.

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

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.

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

out_item_list

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.

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

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.

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

4493PRO_037.HTML