Document revision date: 19 July 1999

This section describes the individual MAIL routines. Input and output item list arguments use item descriptor fields structured as shown in the following diagram:

Item Descriptor Fields

buffer length

For input item lists, this word specifies the length (in bytes) of the buffer that supplies the information needed by the routine to process the specified item code.

For output item lists, this word contains a user-supplied integer specifying the length (in bytes) of the buffer in which the routine is to write the information.

The required length of the buffer depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the routine truncates the data.

item code

For input item lists, a word containing a user-supplied symbolic code that specifies an option for the Mail utility operation. For output item lists, a word containing a user-supplied symbolic code specifying the item of information that the routine is to return. Each programming language provides an appropriate mechanism for defining this information.

buffer address

For input item lists, a longword containing the address of the buffer that supplies information to the routine. For output item lists, a longword containing the user-supplied address of the buffer in which the routine is to write the information.

return length address

This field is not used for input item lists. For output item lists, this field contains a longword specifying the user-supplied address of a longword in which the routine writes the actual length in bytes of the information it returns.

Initiates mail file processing.

Format

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

Mail file context information to be passed to other mail file routines. The context argument is the address of a longword that contains mail file context information.

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

For this routine, there are no input item codes.

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.

The only output item code for this routine is the MAIL$_MAILFILE_MAIL_DIRECTORY item code. When you specify MAIL$_MAILFILE_MAIL_DIRECTORY, MAIL$MAILFILE_BEGIN returns the mail directory specification to the caller. 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$MAILFILE_BEGIN creates and initiates a mail file context for calls to other mail file 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$GET_VM, $GETJPIW, and $GETSYI.

Closes the currently open mail file.

Format

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

Mail file context information to be passed to mail file routines. The context argument is the address of a longword that contains mail file context information returned by MAIL$MAILFILE_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$_MAILFILE_FULL_CLOSE

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE specifies that MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it closes the mail file. If the number of bytes deleted by the purge operation exceeds a system-defined threshold, the Mail utility reclaims the deleted space from the mail file.

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

The system-defined threshold is reserved by Compaq.

out_item_list

Output Item Codes

MAIL$_MAILFILE_DATA_RECLAIM

When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_CLOSE returns the number of data buckets reclaimed during the reclaim operation as a longword value.

MAIL$_MAILFILE_DATA_SCAN

When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_CLOSE returns the number of data buckets scanned during the reclaim operation as a longword value.

MAIL$_MAILFILE_INDEX_RECLAIM

When you specify MAIL$_MAILFILE_INDEX_RECLAIM, MAIL$MAILFILE_CLOSE returns the number of index buckets reclaimed during a reclaim operation as a longword value.

MAIL$_MAILFILE_MESSAGES_DELETED

When you specify MAIL$_MAILFILE_MESSAGES_DELETED, MAIL$MAILFILE_CLOSE returns the number of messages deleted as a longword value.

MAIL$_MAILFILE_TOTAL_RECLAIM

When you specify MAIL$_MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_CLOSE returns the number of bytes reclaimed during a reclaim operation as a longword value.

Description

If you specify the input item code MAIL$_MAILFILE_FULL_CLOSE, this procedure purges the wastebasket folder automatically before it closes the file. If the number of bytes deleted by this procedure exceeds the deleted byte threshold, the system performs a convert/reclaim operation on the file.

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$_NOFILEOPEN	No mail file is open.
SS$_ACCVIO	Access violation.

Compresses a mail file.

Format

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

Mail file context information to be passed to various mail file routines. The context argument is the address of a longword that contains mail file context information returned by MAIL$MAILFILE_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$_MAILFILE_DEFAULT_NAME

MAIL$_MAILFILE_DEFAULT_NAME specifies the default file specification the Mail utility should use when opening a mail file. The buffer address field points to a character string 0 to 255 characters long that defines the default file specification.

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

If you specify the value 0 in buffer length field of the item descriptor, MAIL$MAILFILE_COMPRESS uses the current default directory as the default mail file specification.

If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_COMPRESS creates the default mail file specification from the following sources:

• Disk and directory defined in the caller's user authorization file (UAF)
• Subdirectory defined in the Mail user profile
• Default file type of .MAI

MAIL$_MAILFILE_FULL_CLOSE

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that the wastebasket folder be purged and that convert and reclaim operations be performed, if necessary.

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

MAIL$_MAILFILE_NAME

MAIL$_MAILFILE_NAME specifies the name of a mail file to be opened. The buffer that the buffer address field points to contains a character string of 0 to 255 characters.

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

If you do not specify MAIL$_MAILFILE_NAME, the default mail file name is MAIL.

out_item_list

Output Item Code

MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, the Mail utility returns the resultant mail 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.

Description

If you do not specify an input file, the MAIL$MAILFILE_COMPRESS routine compresses the currently open Mail file. The MAIL$MAILFILE_COMPRESS routine signals informational messages concerning the phase of the compression.

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$_NOTISAM	The message file is not an indexed file.
RMS$_FNF	The specified file cannot be found.
RMS$_SHR	The specified file is not shareable.
SS$_ACCVIO	Access violation.
SS$_IVDEVNAM	The specified device name is invalid.
Any condition value returned by LIB$FIND_IMAGE_SYMBOL, LIB$RENAME_FILE, $CREATE, $OPEN, $PARSE, and $SEARCH.

Terminates mail file processing.

Format

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

Mail file context information to be passed to mail file routines. The context argument is the address of a longword that contains MAILFILE context information returned by MAIL$MAILFILE_BEGIN.

If mail file processing is terminated successfully, the Mail utility sets the value of the argument context 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. 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$_MAILFILE_FULL_CLOSE

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that the wastebasket folder be purged and that convert and reclaim operations be performed, if necessary.

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

out_item_list

Output Item Codes

None.

Description

The MAIL$MAILFILE_END routine deallocates the mail file context created by MAIL$MAILFILE_BEGIN as well as any dynamic memory allocated by other mail file processing 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.

Obtains information about a specified mail file.

Format

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

Mail file context information to be passed to mail file routines. The context argument is the address of a longword that contains mail file context information returned by MAIL$MAILFILE_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$_MAILFILE_DEFAULT_NAME

MAIL$_MAILFILE_DEFAULT_NAME specifies the default mail file specification MAIL$MAILFILE_INFO_FILE should use when opening a mail file. The buffer address field of the item descriptor points to a character string of 0 to 255 characters that defines the default mail file specification.

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

If you specify the value 0 in buffer length field of the item descriptor, MAIL$MAILFILE_INFO_FILE uses the current default directory as the default mail file specification.

If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_INFO_FILE creates the default mail file specification from the following sources:

• Disk and directory defined in the caller's user authorization file (UAF)
• Subdirectory defined in the Mail user profile
• Default file type of .MAI

MAIL$_MAILFILE_FOLDER_ROUTINE

MAIL$_MAILFILE_FOLDER_ROUTINE specifies an entry point longword address of a user-written routine that MAIL$MAILFILE_INFO_FILE should use to display folder names. MAIL$MAILFILE_INFO_FILE calls the user-written routine for each folder in the mail file.

MAIL$_MAILFILE_NAME

MAIL$_MAILFILE_NAME specifies the name of the mail file to be opened. The buffer address field 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.

If you do not specify MAIL$_MAILFILE_NAME, the default mail file name is MAIL.

MAIL$_MAILFILE_USER_DATA

MAIL$_MAILFILE_USER_DATA specifies a longword that MAIL$MAILFILE_INFO_FILE should pass to the user-defined folder name action routine.

This item code is valid only when used with the item code MAIL$_MAILFILE_FOLDER_ROUTINE.

out_item_list

Output Item Codes

MAIL$_MAILFILE_DELETED_BYTES

When you specify MAIL$_MAILFILE_DELETED_BYTES, MAIL$MAILFILE_INFO_FILE returns the number of deleted bytes in a specified mail file as longword value.

MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_INFO_FILE returns the resultant mail 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$_MAILFILE_WASTEBASKET

When you specify MAIL$_MAILFILE_WASTEBASKET, MAIL$MAILFILE_INFO_FILE returns the name of the wastebasket folder of the specified mail file. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 39 characters long.

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

Description

If you do not specify an input file, the MAIL$MAILFILE_INFO_FILE returns information about the currently open mail file.

Folder Action Routines

If you use the item code MAIL$_MAILFILE_FOLDER_ROUTINE to specify a folder name routine, MAIL$MAILFILE_INFO_FILE passes control to a user-specified routine. For example, the folder action routine could display folder names. The user routine must return a 32-bit integer code. If the return code indicates success, the interaction between the user's routine and the callable routine can continue.

The folder action routine passes a pointer to the descriptor of a folder name as well as the user data longword. A descriptor of zero length indicates that the MAIL$MAILFILE_INFO_FILE routine has displayed all folder names. If you do not specify the item code MAIL$_MAILFILE_FOLDER_ROUTINE, MAIL$MAILFILE_INFO_FILE does not call any folder action 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.
MAIL$_NOFILEOPEN	The mail file is not open.
MAIL$_NOTISAM	The message file is not an indexed file.
MAIL$_OPENIN	Mail cannot open the file as input.
SS$_ACCVIO	Access violation.
Any condition value returned by $CLOSE, $OPEN, $PARSE, and $SEARCH.

	privacy and legal statement
4493PRO_033.HTML