[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

OpenVMS Utility Routines Manual


Previous Contents Index


MAIL$MAILFILE_END

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


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

MAIL$MAILFILE_INFO_FILE

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


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

MAIL$MAILFILE_MODIFY

Modifies the informational record of an indexed mail file, including the mail file name, the default mail file name, and the wastebasket name.

Format

MAIL$MAILFILE_MODIFY 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 file specification that the Mail utility should use when opening a mail file. The buffer address field points to a buffer that contains 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 the buffer length field of the item descriptor, MAIL$MAILFILE_MODIFY uses the current default directory as the default mail file specification.

If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_MODIFY 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_NAME

MAIL$_MAILFILE_NAME specifies the name of the mail file that the Mail utility should open. The buffer address field points to a buffer that 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.

MAIL$_MAILFILE_WASTEBASKET_NAME

MAILFILE_WASTEBASKET_NAME specifies a new folder name for the wastebasket in the specified mail file. The buffer address field points to a buffer that contains a character string of 1 to 39 characters.

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$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, the Mail utility returns the resultant mail file specification. The buffer address field points to a buffer that receives a character string from 0 to 255 characters long.

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


Description

If a mail file is not specified, the currently open mail file is used.


Condition Values Returned

MAIL$_ILLFOLNAM The specified folder name 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.
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, $FIND, $PUT, and $UPDATE.

MAIL$MAILFILE_OPEN

Opens a specified mail file for processing. You must use this routine to open a mail file before you can do either of the following:
  • Call any mail file routines to manipulate mail files
  • Call message routines to read messages from the specified mail file

Format

MAIL$MAILFILE_OPEN 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 file specification MAIL$MAILFILE_OPEN should use when opening a mail file. The buffer address field points to a character string of 0 to 255 characters 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 the buffer length field of the item descriptor, MAIL$MAILFILE_OPEN uses the current default directory as the default mail file specification.

If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_OPEN 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_NAME

MAIL$_MAILFILE_NAME specifies the name of the mail file MAIL$MAILFILE_OPEN should open. The buffer address field points to a buffer that 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 MAIL$_MAILFILE_NAME, the default mail file name is MAIL.

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$_MAILFILE_DELETED_BYTES

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

MAIL$_MAILFILE_INDEXED

When you specify MAIL$_MAILFILE_INDEXED, MAIL$MAILFILE_OPEN returns a Boolean TRUE when you open an indexed file. The buffer length field points to a longword that receives the Boolean value.

MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_OPEN 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_OPEN returns the name of the wastebasket for the specified mail file. 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

The default mail file specification is MAIL.MAI in the MAIL subdirectory.

Condition Values Returned

MAIL$_FILEOPEN The mail file is already open.
MAIL$_INVITMCOD The specified item code is invalid.
MAIL$_INVITMLEN The specified item length is invalid.
MAIL$_MISREQITEM The required item is missing.
MAIL$_NOMSGS No messages are available.
SS$_ACCVIO Access violation.
Any condition value returned by LIB$GET_VM, $CONNECT, and $OPEN.


Previous Next Contents Index