OpenVMS Utility Routines Manual
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.
|
|
