Updated: 11 December 1998

OpenVMS Utility Routines Manual

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.

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

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.

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.

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

MAIL$_USER_SUB_DIRECTORY

When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_BEGIN returns the subdirectory specification. 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$USER_BEGIN creates and initializes a user database context for subsequent calls to other user routines.

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.

Removes a record from the user profile database.

Format

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

User context information to be passed to send routines. The context argument is the address of a longword that contains user context information returned by MAIL$USER_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 must include at least one device item descriptor. The item list is terminated by longword value of 0.

Input Item Codes

MAIL$_USER_USERNAME

MAIL$_USER_USERNAME specifies the record to be deleted from the user profile database. The buffer address field of the item descriptor points to a buffer that contains the user name string encoded in a character string 0 to 31 characters long.

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

The item code MAIL$_USER_USERNAME is required.

out_item_list

Output Item Codes

None.

Description

To delete a record from the user profile database, you must have SYSPRV privilege.

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.
MAIL$_NOSUCHUSR	The specified user name is not valid.
MAIL$_NOSYSPRV	The operation requires the SYSPRV privilege.
SS$_ACCVIO	Access violation.

Terminates access to the user profile database.

Format

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

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

If the Mail utility terminates access to the user profile database successfully, the value of 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$USER_END routine deallocates the user database context created by MAIL$USER_BEGIN as well as all dynamic memory allocated by previous user routines.

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.

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

4493PRO_038.HTML