HP 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:

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