Updated: 11 December 1998

OpenVMS Utility Routines Manual

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

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.

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

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.

Deletes messages contained in the wastebasket folder of the currently open mail file.

Format

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

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_RECLAIM

The Boolean item code MAIL$_MAILFILE_RECLAIM specifies that MAIL$MAILFILE_PURGE_WASTE purge the wastebasket folder and reclaim deleted space in the mail file.

Specify the value 0 in the buffer length field of the item descriptor.

MAIL$_MAILFILE_RECLAIM explicitly requests a reclaim operation and overrides the deleted byte's threshold regardless of the number of bytes deleted during a mail file purge operation.

out_item_list

Output Item Codes

MAIL$_MAILFILE_DATA_RECLAIM

When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_PURGE_WASTE 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_PURGE_WASTE 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, the Mail utility returns the number of index buckets reclaimed during a reclaim operation as a longword value.

MAIL$_MAILFILE_DELETED_BYTES

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

MAIL$_MAILFILE_MESSAGES_DELETED

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

MAIL$_MAILFILE_TOTAL_RECLAIM

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

Description

If you specify the MAIL$_MAILFILE_RECLAIM item descriptor, all the bytes deleted from the mail file by this routine are reclaimed.

Condition Values Returned

MAIL$_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 currently open.
MAIL$_NOTISAM	The message file is not an indexed file.
SS$_ACCVIO	Access violation.

Begins message processing. You must call this routine before calling any other message routines.

Format

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

Message context information to be passed to various message routines. The context argument is the address of a longword that contains message context information.

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

MAIL$_MESSAGE_FILE_CTX specifies the mail file context received from MAIL$MAILFILE_BEGIN to be passed to the message routines. The buffer address field of the item descriptor points to a longword that contains mail file context information.

The item code MAIL$_MESSAGE_FILE_CTX is required.

out_item_list

Output Item Code

MAIL$_MESSAGE_SELECTED

When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_BEGIN returns the number of messages selected as a longword value.

Description

MAIL$MESSAGE_BEGIN creates and initializes a message context for subsequent calls to message routines.

Condition Values Returned

MAIL$_ILLCTXADR	The context block address 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$_NOFILEOPEN	The mail file is not open.
MAIL$_WRONGCTX	The context block is incorrect.
MAIL$_WRONGFILE	The specified file is incorrect in this context.
SS$_ACCVIO	Access violation.
Any condition value returned by $GET and LIB$GET_VM.

Copies messages between files or folders.

Format

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

Message context information to be passed to message routines. The context argument is the address of a longword that contains message context information returned by MAIL$MESSAGE_BEGIN.

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

When you specify the Boolean item code MAIL$_MESSAGE_BACK, MAIL$MESSAGE_COPY copies the message preceding the current message.

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

Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.

MAIL$_MESSAGE_DEFAULT_NAME

MAIL$_MESSAGE_DEFAULT_NAME specifies the default file specification of a mail file to open in order to copy a message. 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$_MESSAGE_DELETE

When you specify the Boolean item code MAIL$_MESSAGE_DELETE, MAIL$MESSAGE_COPY deletes the message in the current folder after the message has been copied to a destination folder.

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

Specify MAIL$_MESSAGE_DELETE to emulate the operation of MAIL MOVE or FILE command.

MAIL$_MESSAGE_FILE_ACTION

MAIL$_MESSAGE_FILE_ACTION specifies the address of the mail file action routine called if a mail file is to be created. Two parameters are passed as follows:

• User data longword
• Address of the descriptor of the file name to be created

The buffer address field of the item descriptor points to a longword that denotes a procedure value.

MAIL$_MESSAGE_FILENAME

MAIL$_MESSAGE_FILENAME specifies the name of the mail file to which the current message will be moved. 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$_MESSAGE_FOLDER

MAIL$_MESSAGE_FOLDER specifies the name of the target folder for moving mail messages. 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 item code MAIL$_MESSAGE_FOLDER is required.

MAIL$_MESSAGE_FOLDER_ACTION

MAIL$_MESSAGE_FOLDER_ACTION specifies the entry point address of the folder action routine called if a folder is to be created. Two parameters are passed as follows:

• User data longword
• Address of a descriptor of the folder name to be created.

The buffer address field of the item descriptor points to a longword that specifies a procedure value.

MAIL$_MESSAGE_ID

MAIL$_MESSAGE_ID specifies the message identification number of the message on which the operation is to be performed. The buffer address field of the item descriptor points to a longword that contains the message identification number.

Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.

MAIL$_MESSAGE_NEXT

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, the Mail utility copies the message following the current message.

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

---

Previous

Next

Contents

Index

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

4493PRO_034.HTML