[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Utility Routines Manual


Previous Contents Index


MAIL$MAILFILE_PURGE_WASTE

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


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

MAIL$MESSAGE_BEGIN

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


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

MAIL$MESSAGE_COPY

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.

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

MAIL$_MESSAGE_USER_DATA

MAIL$_MESSAGE_USER_DATA specifies data passed to the folder action and mail file action routines. The buffer address field of the item descriptor points to a user data longword.

Specify MAIL$_MESSAGE_USER_DATA with the item codes MAIL$_MESSAGE_FILE_ACTION and MAIL$_MESSAGE_FOLDER_ACTION only.

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

When you specify the Boolean item code MAIL$_MESSAGE_FILE_CREATED, MAIL$MESSAGE_COPY returns the value of the file created flag as longword value.

MAIL$_MESSAGE_FOLDER_CREATED

When you specify the Boolean item code MAIL$_MESSAGE_FOLDER_CREATED, MAIL$MESSAGE_COPY returns the value of the folder created flag as a longword value.

MAIL$_MESSAGE_RESULTSPEC

When you specify MAIL$_MESSAGE_RESULTSPEC, MAIL$MESSAGE_COPY returns the mail file resultant 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 a file name, the routine copies the message to another folder in the currently open mail file. The target mail file must be an indexed file.

Condition Values Returned

SS$_NORMAL Normal successful completion.
MAIL$_BADVALUE The specified keyword value is invalid.
MAIL$_CONITMCOD The specified item codes define conflicting operations.
MAIL$_DATIMUSED The date and time is currently used in the specified file.
MAIL$_DELMSG The message is deleted.
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$_MSGINFO Informational records are successfully returned.
MAIL$_MSGTEXT Text record is successfully returned.
MAIL$_NOFILEOPEN The mail file is not open.
MAIL$_NOMOREREC No more records can be found.
MAIL$_NOTREADIN The operation is invalid; you are not reading a message.
MAIL$_RECTOBIG The record is too large for the MAIL buffer.
MAIL$_WRONGCTX The context block is incorrect.
MAIL$_WRONGFILE The specified file is incorrect in this context.
SS$_IVDEVNAM The device name is invalid.
SS$_ACCVIO Access violation.
Any condition value returned by $CONNECT, $CREATE, $OPEN, $WRITE, $READ, and $PUT.

MAIL$MESSAGE_DELETE

Deletes a specified message from the currently selected folder.

Format

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

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_ID

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

The item code MAIL$_MESSAGE_ID is required.

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

When you delete a message from a selected folder, it is moved to the wastebasket folder. You cannot delete a message from the wastebasket folder. You must use the MAIL$MAILFILE_PURGE_WASTE routine to empty the wastebasket folder.

Condition Values Returned

SS$_NORMAL Normal successful completion.
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.


Previous Next Contents Index