Document revision date: 30 March 2001

## 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

| privacy and legal statement |
4493PRO_040.HTML