OpenVMS Utility Routines Manual
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.
|
[an error occurred while processing this directive]
|
