The callable interface of the Mail utility (MAIL) lets you
send messages to users on your system or on any other computer
connected to your system with DECnet.
1 – MAIL$MAILFILE_BEGIN
Initiates mail file processing.
Format
MAIL$MAILFILE_BEGIN context ,in_item_list ,out_item_list
1.1 – 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.
1.2 – 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.
You should specify the value of this argument as 0 in the first
of a sequence of calls to mail file routines. In the following
calls, you should specify the mail file 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 a longword value of 0.
For this routine, there are no input item codes.
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.
The only output item code for this routine is the MAIL$_MAILFILE_
MAIL_DIRECTORY item code. When you specify MAIL$_MAILFILE_
MAIL_DIRECTORY, MAIL$MAILFILE_BEGIN returns the mail directory
specification to the caller. 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_BEGIN creates and initiates a mail file context for
calls to other mail file routines.
1.3 – 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$GET_VM, $GETJPIW, and
$GETSYI.
2 – MAIL$MAILFILE_CLOSE
Closes the currently open mail file.
Format
MAIL$MAILFILE_CLOSE context ,in_item_list ,out_item_list
2.1 – 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.
2.2 – 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.
2.3 – Input Item Codes
MAIL$_MAILFILE_FULL_CLOSE
The Boolean item code MAIL$_MAILFILE_FULL_CLOSE specifies that
MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it
closes the mail file. If the number of bytes deleted by the purge
operation exceeds a system-defined threshold, the Mail utility
reclaims the deleted space from the mail file.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
The system-defined threshold is reserved by VSI.
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.
2.4 – Output Item Codes
MAIL$_MAILFILE_DATA_RECLAIM
When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_CLOSE
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_CLOSE
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, MAIL$MAILFILE_
CLOSE returns the number of index buckets reclaimed during a
reclaim operation as a longword value.
MAIL$_MAILFILE_MESSAGES_DELETED
When you specify MAIL$_MAILFILE_MESSAGES_DELETED, MAIL$MAILFILE_
CLOSE returns the number of messages deleted as a longword value.
MAIL$_MAILFILE_TOTAL_RECLAIM
When you specify MAIL$_MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_
CLOSE returns the number of bytes reclaimed during a reclaim
operation as a longword value.
2.5 – Description
If you specify the input item code MAIL$_MAILFILE_FULL_CLOSE,
this procedure purges the wastebasket folder automatically
before it closes the file. If the number of bytes deleted by this
procedure exceeds the deleted byte threshold, the system performs
a convert/reclaim operation on the file.
2.6 – 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.
MAIL$_NOFILEOPEN No mail file is open.
SS$_ACCVIO Access violation.
3 – MAIL$MAILFILE_COMPRESS
Compresses a mail file.
Format
MAIL$MAILFILE_COMPRESS context ,in_item_list ,out_item_list
3.1 – 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.
3.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Mail file context information to be passed to various 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.
3.3 – Input Item Codes
MAIL$_MAILFILE_DEFAULT_NAME
MAIL$_MAILFILE_DEFAULT_NAME specifies the default file
specification the Mail utility should use when opening a mail
file. The buffer address field points to a character string 0 to
255 characters long 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 buffer length field of the item
descriptor, MAIL$MAILFILE_COMPRESS uses the current default
directory as the default mail file specification.
If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_
COMPRESS creates the default mail file specification from the
following sources:
o Disk and directory defined in the caller's user authorization
file (UAF)
o Subdirectory defined in the Mail user profile
o Default file type of .MAI
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.
MAIL$_MAILFILE_NAME
MAIL$_MAILFILE_NAME specifies the name of a mail file to be
opened. The buffer that the buffer address field points to
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.
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.
3.4 – 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 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.
3.5 – Description
If you do not specify an input file, the MAIL$MAILFILE_
COMPRESS routine compresses the currently open Mail file. The
MAIL$MAILFILE_COMPRESS routine signals informational messages
concerning the phase of the compression.
3.6 – 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.
MAIL$_NOTISAM The message file is not an indexed file.
RMS$_FNF The specified file cannot be found.
RMS$_SHR The specified file is not shareable.
SS$_ACCVIO Access violation.
SS$_IVDEVNAM The specified device name is invalid.
Any condition value returned by LIB$FIND_IMAGE_SYMBOL,
LIB$RENAME_FILE, $CREATE, $OPEN, $PARSE, and $SEARCH.
4 – MAIL$MAILFILE_END
Terminates mail file processing.
Format
MAIL$MAILFILE_END context ,in_item_list ,out_item_list
4.1 – 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.
4.2 – 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.
4.3 – 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.
4.4 – Output Item Codes
None.
4.5 – 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.
4.6 – 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.
5 – MAIL$MAILFILE_INFO_FILE
Obtains information about a specified mail file.
Format
MAIL$MAILFILE_INFO_FILE context ,in_item_list ,out_item_list
5.1 – 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.
5.2 – 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.
5.3 – 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:
o Disk and directory defined in the caller's user authorization
file (UAF)
o Subdirectory defined in the Mail user profile
o 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.
5.4 – 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.
5.5 – 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.
5.6 – 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.
6 – 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
6.1 – 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.
6.2 – 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.
6.3 – 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:
o Disk and directory defined in the caller's user authorization
file (UAF)
o Subdirectory defined in the Mail user profile
o 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.
6.4 – 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.
6.5 – Description
If a mail file is not specified, the currently open mail file is
used.
6.6 – 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.
7 – 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:
o Call any mail file routines to manipulate mail files
o Call message routines to read messages from the specified mail
file
Format
MAIL$MAILFILE_OPEN context ,in_item_list ,out_item_list
7.1 – 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.
7.2 – 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.
7.3 – 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:
o Disk and directory defined in the caller's user authorization
file (UAF)
o Subdirectory defined in the Mail user profile
o 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.
7.4 – 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.
7.5 – Description
The default mail file specification is MAIL.MAI in the MAIL
subdirectory.
7.6 – 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.
8 – 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
8.1 – 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.
8.2 – 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.
8.3 – 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.
8.4 – 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.
8.5 – Description
If you specify the MAIL$_MAILFILE_RECLAIM item descriptor,
all the bytes deleted from the mail file by this routine are
reclaimed.
8.6 – 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.
9 – 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
9.1 – 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.
9.2 – 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.
9.3 – 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.
9.4 – 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.
9.5 – Description
MAIL$MESSAGE_BEGIN creates and initializes a message context for
subsequent calls to message routines.
9.6 – 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.
10 – MAIL$MESSAGE_COPY
Copies messages between files or folders.
Format
MAIL$MESSAGE_COPY context ,in_item_list ,out_item_list
10.1 – 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.
10.2 – 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.
10.3 – 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:
o User data longword
o 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:
o User data longword
o 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.
10.4 – 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.
10.5 – 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.
10.6 – 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.
11 – MAIL$MESSAGE_DELETE
Deletes a specified message from the currently selected folder.
Format
MAIL$MESSAGE_DELETE context ,in_item_list ,out_item_list
11.1 – 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.
11.2 – 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.
11.3 – 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.
11.4 – Output Item Codes
None.
11.5 – 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.
11.6 – 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.
12 – MAIL$MESSAGE_END
Ends message processing.
Format
MAIL$MESSAGE_END context ,in_item_list ,out_item_list
12.1 – 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.
12.2 – 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. If
message processing ends successfully, the argument context is
changed 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. This routine does
not use the in_item_list argument.
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. This routine does not use the out_item_list argument.
12.3 – Description
The MAIL$MESSAGE_END routine deallocates the message context
created by MAIL$MESSAGE_BEGIN as well as any dynamic memory
allocated by other message routines.
12.4 – 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.
SS$_ACCVIO Access violation.
Any condition value returned by LIB$FREE_VM.
13 – MAIL$MESSAGE_GET
Retrieves a message from the set of currently selected messages.
Format
MAIL$MESSAGE_GET context ,in_item_list ,out_item_list
13.1 – 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.
13.2 – 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.
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.
13.3 – Input Item Codes
MAIL$_MESSAGE_AUTO_NEWMAIL
When you specify the Boolean item code MAIL$_MESSAGE_AUTO_
NEWMAIL, MAIL$MESSAGE_GET automatically places a new message
in the mail folder as it is read. MAIL$_MESSAGE_AUTO_NEWMAIL
is valid only when specified with the item code MAIL$_MESSAGE_
CONTINUE.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_MESSAGE_BACK
When you specify the Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_GET reads the message identification number of a
specified message to return the first record of the preceding
message.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_CONTINUE
When you specify the Boolean item code MAIL$_MESSAGE_CONTINUE,
MAIL$MESSAGE_GET reads the message identification number of a
specified message to return the next text record of the current
message.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_ID
MAIL$_MESSAGE_ID specifies the message identification number of
a message on which an 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 the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_NEXT
When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_GET reads the message identification number of
a specified message to return the first record of 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 the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same
call to MAIL$MESSAGE_GET.
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.
13.4 – Output Item Codes
MAIL$_MESSAGE_BINARY_DATE
When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_GET
returns the message arrival date as a quadword binary value.
MAIL$_MESSAGE_CC
When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_GET returns the
CC: field of the current message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_CURRENT_ID
When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_GET
returns the message identification number of the current message.
The buffer address field of the item descriptor points to a
longword that receives the message identifier number.
MAIL$_MESSAGE_DATE
When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_GET returns
the message creation date string. 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$_MESSAGE_EXTID
MAIL$_MESSAGE_EXTID specifies the external message identification
number of the current message. The buffer address field of the
item descriptor points to a buffer that contains a character
string 0 to 255 characters long.
MAIL$_MESSAGE_FROM
When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_GET returns the
From: field of the specified message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_RECORD
When you specify MAIL$_MESSAGE_RECORD, MAIL$MESSAGE_GET returns
a record of the message. The buffer address field of the item
descriptor points to a buffer that receives a character string 0
to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_RECORD is valid only when specified with the item
code MAIL$_MESSAGE_CONTINUE.
Do not specify MAIL$_MESSAGE_RECORD with the following item
codes:
o MAIL$_MESSAGE_BACK
o MAIL$_MESSAGE_ID
o MAIL$_MESSAGE_NEXT
MAIL$_MESSAGE_RECORD_TYPE
When you specify MAIL$_MESSAGE_RECORD_TYPE, MAIL$MESSAGE_
GET returns the record type. A record may be either header
information (MAIL$_MESSAGE_HEADER) or text (MAIL$_MESSAGE_TEXT).
The buffer address field of the item descriptor points to a word
that receives the record type.
MAIL$_MESSAGE_RETURN_FLAGS
When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_GET
returns the Mail system flag for the current message as a 2-byte
bit mask value.
MAIL$_MESSAGE_SENDER
When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_GET returns
the name of the sender of the current message. The buffer address
field of the item descriptor points to a buffer that receives a
character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_SIZE
When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_GET returns the
size in records of the current message as a longword value.
MAIL$_MESSAGE_SUBJECT
When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_GET returns
the Subject: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a
character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_TO
When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_GET returns the
To: field of the specified message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
13.5 – Description
The first time the MAIL$MESSAGE_GET routine is called, the
message information is returned for the first requested message,
and the status returned is MAIL$_MSGINFO. Subsequent calls to
MAIL$MESSAGE_GET with the MAIL$_MESSAGE_CONTINUE item code return
the message text records with the status MAIL$_MSGTEXT, until no
more records are left, when MAIL$_NOMOREREC is returned.
13.6 – Condition Values Returned
MAIL$_MSGINFO Informational records are successfully
returned.
MAIL$_MSGTEXT Text record is successfully 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$_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$_ACCVIO Access violation.
Any condition value returned by $FIND and $UPDATE.
14 – MAIL$MESSAGE_INFO
Obtains information about a specified message contained in the
set of currently selected messages.
Format
MAIL$MESSAGE_INFO context ,in_item_list ,out_item_list
14.1 – 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.
14.2 – 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.
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.
14.3 – Input Item Codes
MAIL$_MESSAGE_BACK
When you specify Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_INFO reads the identification number of the current
message and returns the preceding 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_INFO.
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_INFO.
MAIL$_MESSAGE_NEXT
When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_INFO reads the message identification number of
the current message and returns the message that follows it.
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_INFO.
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.
14.4 – Output Item Codes
MAIL$_MESSAGE_BINARY_DATE
When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_INFO
returns the message arrival date as a quadword binary value.
MAIL$_MESSAGE_CC
When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_INFO returns the
CC: field of the current message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_CURRENT_ID
When you specify MAIL$_MESSAGE_ID, MAIL$MESSAGE_INFO returns
the message identification number of the current message. The
buffer address field of the item descriptor points to a longword
that receives the message identification number of the current
message.
MAIL$_MESSAGE_DATE
When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_INFO returns
the message creation date string. 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$_MESSAGE_EXTID
When you specify MAIL$_MESSAGE_EXTID, MAIL$MESSAGE_INFO returns
the external identification number of the current message as a
string. 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$_MESSAGE_FROM
When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_INFO returns
the From: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a
character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_REPLY_PATH
When you specify MAIL$_MESSAGE_REPLY_PATH, MAIL$MESSAGE_INFO
returns the reply path of the specified message. The buffer
address field of the item descriptor points to a buffer that
receives a character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_RETURN_FLAGS
When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_INFO
returns the Mail system flag values for the current message as a
2-byte bit mask value.
MAIL$_MESSAGE_SENDER
When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_INFO returns
the name of the sender of the current message. The buffer address
field of the item descriptor points to a buffer that receives a
character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_SIZE
When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_INFO returns
the size of the current message in records as a longword value.
MAIL$_MESSAGE_SUBJECT
When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_INFO returns
the Subject: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a
character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_TO
When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_INFO returns the
To: field of the specified message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
14.5 – Description
MAIL$MESSAGE_INFO obtains information about a particular message.
MAIL$MESSAGE_GET retrieves a message from the set of currently
selected messages.
The first call to MAIL$MESSAGE_GET passes control to
MAIL$MESSAGE_INFO. Subsequent calls that include the MAIL$_
MESSAGE_CONTINUE item code return text records.
14.6 – Condition Values Returned
MAIL$_CONITMCOD The specified item codes define conflicting
operations.
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$_NOFILEOPEN The mail file is not open.
MAIL$_NOMOREMSG No more messages.
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 LIB$GET_VM.
15 – MAIL$MESSAGE_MODIFY
Modifies information in the message header.
Format
MAIL$MESSAGE_MODIFY context ,in_item_list ,out_item_list
15.1 – 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.
15.2 – 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.
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.
15.3 – Input Item Codes
MAIL$_MESSAGE_BACK
When you specify the Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_MODIFY reads the identification number of the
specified message in order to return the first record in the
preceding message.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_
MODIFY.
MAIL$_MESSAGE_FLAGS
MAIL$_MESSAGE_FLAGS specifies system flags for new mail. The
buffer address field of the item descriptor points to a word that
contains bit mask offsets. The following offsets can be used to
modify the 2-byte bit mask:
o MAIL$V_replied
o MAIL$V_marked
MAIL$_MESSAGE_ID
MAIL$_MESSAGE_ID specifies the message identification number of
the message on which an 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 the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_
MODIFY.
MAIL$_MESSAGE_NEXT
When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_MODIFY reads the message identification number of
a message and returns the first record in 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 the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_
MODIFY.
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.
15.4 – Output Item Code
MAIL$_MESSAGE_CURRENT_ID
When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_MODIFY
returns the message identification number of the current message.
The buffer address field of the item descriptor points to a
longword that receives the message identification number.
15.5 – Condition Values Returned
MAIL$_CONITMCOD The specified item codes define conflicting
operations.
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$_NOFILEOPEN The mail file is not open.
MAIL$_NOMOREMSG No more messages.
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 $FIND and $UPDATE.
16 – MAIL$MESSAGE_SELECT
Selects a message or messages from the currently open mail file.
Before you attempt to read a message, you must select it.
Format
MAIL$MESSAGE_SELECT context ,in_item_list ,out_item_list
16.1 – 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.
16.2 – 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.
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.
16.3 – Input Item Codes
MAIL$_MESSAGE_BEFORE
When you specify MAIL$_MESSAGE_BEFORE, MAIL$MESSAGE_SELECT
selects a message received before a specified date and time. The
buffer address field of the item descriptor points to a buffer
that contains a character string 0 to 255 characters long in
absolute time.
Specify a value from 0 to 255 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_CC_SUBSTRING
MAIL$_MESSAGE_CC_SUBSTRING specifies a character string that must
match a substring contained in the CC: field of the specified
message. If the strings match, the message is selected. The
buffer address field of the item descriptor points to a buffer
that receives a character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_FLAGS
MAIL$_MESSAGE_FLAGS specifies bit masks that must be initialized
to 1.
MAIL$_MESSAGE_FLAGS_MBZ
MAIL$_MESSAGE_FLAGS_MBZ specifies Mail system flags that must be
set to 0.
MAIL$_MESSAGE_FOLDER
MAIL$_MESSAGE_FOLDER specifies the name of the folder that
contains messages to be selected.
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.
This item code is required.
MAIL$_MESSAGE_FROM_SUBSTRING
MAIL$_MESSAGE_FROM_SUBSTRING specifies a user-specified character
string that must match the substring contained in the From: field
of a specified message. If the strings match, the message is
selected.
The buffer address field of the item descriptor points to a
buffer that receives a character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_SINCE
When you specify MAIL$_MESSAGE_SINCE, the Mail utility selects a
message received on or after a specified date and time.
The buffer address field of the item descriptor points to a
buffer that contains a character string 0 to 255 characters long
in absolute time.
Specify a value from 0 to 255 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_TO_SUBSTRING
MAIL$_MESSAGE_TO_SUBSTRING specifies a user-specified character
string that must match a substring contained in the To: field
of a specified message. If the strings match, the message is
selected.
The buffer address field of the item descriptor points to a
buffer that contains a character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_MESSAGE_SUBJ_SUBSTRING
MAIL$_MESSAGE_SUBJ_SUBSTRING specifies a user-specified character
string that must match a substring contained in the Subject:
field of a specified message. If the strings match, the message
is selected.
The buffer address field of the item descriptor points to a
buffer that contains a character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field 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.
16.4 – Output Item Code
MAIL$_MESSAGE_SELECTED
When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_SELECT
returns the number of selected messages as a longword value.
16.5 – Description
MAIL$MESSAGE_SELECT deselects previously selected messages
whether or not you request a valid selection.
16.6 – 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$_INVQUAVAL The specified qualifier is invalid
MAIL$_MISREQITEM The required item is missing.
MAIL$_NOFILEOPEN The mail file is not open.
MAIL$_NOTEXIST The specified folder does not exist.
MAIL$_NOTISAM The operation applies only to indexed files.
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 LIB$GET_VM.
17 – MAIL$SEND_ABORT
Cancels a currently executing send operation.
Format
MAIL$SEND_ABORT context ,in_item_list ,out_item_list
17.1 – 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 Value Returned.
17.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Send context information to be passed to send routines. The
context argument is the address of a longword that contains send
context information returned by MAIL$SEND_BEGIN.
in_item_list
OpenVMS usage:itmlst_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying options for the routine. This routine does
not use the in_item_list argument.
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. This routine does not use the out_item_list argument.
17.3 – Description
MAIL$SEND_ABORT is useful when, for example, the user presses
Ctrl/C during the execution of MAIL$SEND_MESSSAGE.
17.4 – Condition Value Returned
SS$_NORMAL Normal successful completion.
18 – MAIL$SEND_ADD_ADDRESS
Adds an address to the address list. If an address list does not
exist, MAIL$SEND_ADD_ADDRESS creates one.
Format
MAIL$SEND_ADD_ADDRESS context ,in_item_list ,out_item_list
18.1 – 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.
18.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Send context information to be passed to send routines. The
context argument is the address of a longword that contains send
context information returned by MAIL$SEND_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.
18.3 – Input Item Codes
MAIL$_SEND_USERNAME
MAIL$_SEND_USERNAME specifies that the Mail utility add a
specified user name to the address list. 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.
The item code MAIL$_SEND_USERNAME is required.
MAIL$_SEND_USERNAME_TYPE
MAIL$_SEND_USERNAME_TYPE specifies the type of user name added to
the address list. The buffer address field of the item descriptor
points to a word that contains the user name type.
There are two types of user names, as follows:
o User name specified as a To: address (default)
o User name specified as a CC: address
NOTE
Currently, the symbols MAIL$_TO and MAIL$_CC define user
name types.
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.
18.4 – Output Item Codes
None.
18.5 – Description
If you do not specify a MAIL$_SEND_USERNAME_TYPE, MAIL$SEND_ADD_
ADDRESS uses MAIL$_TO. You can specify only one user name per
call to MAIL$SEND_ADD_ADDRESS.
18.6 – 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.
SS$_ACCVIO Access violation.
Any condition values returned by LIB$TPARSE.
19 – MAIL$SEND_ADD_ATTRIBUTE
Adds an attribute, such as Subject or To, to the message you are
currently constructing.
Format
MAIL$SEND_ADD_ATTRIBUTE context ,in_item_list ,out_item_list
19.1 – 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.
19.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Send context information to be passed to send routines. The
context argument is the address of a longword that contains send
context information returned by MAIL$SEND_BEGIN.
You should specify this argument as 0 in the first of a sequence
of calls to MAIL routines. In following calls, you should specify
the Send 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.
19.3 – Input Item Codes
MAIL$_SEND_CC_LINE
MAIL$_SEND_CC_LINE specifies a descriptor of the CC: field text.
The buffer address field of the item descriptor points to a
buffer that contains a character string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_SEND_FROM_LINE
MAIL$_SEND_FROM_LINE specifies a descriptor of the From: field
text of the message to be sent. The buffer address field of the
item descriptor points to a buffer that contains a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
Calls to MAIL$SEND_ADD_ATTRIBUTE using this input item code must
be made before any calls to MAIL$SEND_ADD_ADDRESS.
The SYSPRV privilege is required to alter the From: of a message.
MAIL$_SEND_SUBJECT
MAIL$_SEND_SUBJECT specifies a descriptor of the Subject: field
text of a message to be sent. The buffer address field of the
item descriptor points to a buffer that contains a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
MAIL$_SEND_TO_LINE
MAIL$_SEND_TO_LINE specifies a descriptor of the To: field text
of the message. The buffer address field of the item descriptor
points to a buffer that receives a character string 0 to 998
characters long.
Specify a value from 0 to 998 in the buffer length field 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.
19.4 – Output Item Codes
None.
19.5 – Description
If you do not specify a To: line, the Mail utility supplies a
To: line composed of user names on the To: address list. If you
do not specify a CC: line, the Mail utility supplies a CC: line
composed of user names on the CC: address list. In either of the
above cases, commas separate the user names.
To add a message's From: field, you must have the SYSPRV
privilege, and the Mail DECnet object must have the SYSPRV
privilege on OUTGOING CONNECT (users can set the DECnet object
privileges at their discretion).
19.6 – 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.
20 – MAIL$SEND_ADD_BODYPART
Builds the body of a message.
Format
MAIL$SEND_ADD_BODYPART context ,in_item_list ,out_item_list
20.1 – 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.
20.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Send context information to be passed to send routines. The
context argument is the address of a longword that contains send
context information returned by MAIL$SEND_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.
See MAIL$SEND_BEGIN for a description of an input item
descriptor.
20.3 – Input Item Codes
MAIL$_SEND_DEFAULT_NAME
MAIL$_SEND_DEFAULT_NAME specifies the default file specification
of a text file to be opened. 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$_SEND_FID
MAIL$_SEND_FID specifies the file identifier of the text file
to be opened. The buffer address field of the item descriptor
points to a buffer that contains the file identifier. To identify
a file using a file identifier, you must also specify the device
identifier for the file. Specify the device identifier using the
MAIL$_SEND_DEFAULT_NAME item code. More information about using
a file ID for specifying files can be found in OpenVMS Record
Management Services Reference Manual. Note that the MAIL$_SEND_
FID item code and the MAIL$_SEND_FILENAME item code are mutually
exclusive.
MAIL$_SEND_FILENAME
MAIL$_SEND_FILENAME specifies the input file specification of
the text file to be opened. The buffer address field of the item
descriptor points to a buffer that receives a character string
0 to 255 characters long. Note that the MAIL$_SEND_FILENAME item
code and the MAIL$_SEND_FID item code are mutually exclusive.
Specify a value from 0 to 255 in the buffer length field of the
item descriptor.
MAIL$_SEND_RECORD
MAIL$_SEND_RECORD specifies a descriptor of a text record to be
added to the body of the message. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 998 characters long.
Specify a value from 0 to 998 in the buffer length field of the
item descriptor.
When creating a message, do not specify MAIL$_SEND_RECORD in the
same call (or series of calls) to MAIL$SEND_ADD_BODYPART with the
following item codes:
o MAIL$_SEND_FID
o MAIL$_SEND_FILENAME
NOTE
Do not use the MAIL$_SEND_RECORD item code with the
MAIL$SEND_ADD_BODYPART routine called from a detached
process. The routine creates a temporary file in SYS$SCRATCH
that is inaccessible to the detached process.
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.
20.4 – Output Item Code
MAIL$_SEND_RESULTSPEC
When you specify MAIL$_SEND_RESULTSPEC, MAIL$SEND_ADD_BODYPART
returns the resultant file specification identified with MAIL$_
SEND_FILENAME. 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.
20.5 – Description
You can use MAIL$SEND_ADD_BODYPART to specify a file that
contains the entire message or to add a single record to a
message. If the message is contained in a file, you call
MAIL$SEND_ADD_BODYPART once, specifying the file name. If
you want to add to the message record-by-record, you can call
MAIL$SEND_ADD_BODYPART repeatedly, specifying a different record
each time until you complete the message.
You cannot specify both a file name and a record for the same
message. You can specify either MAIL$_SEND_FILENAME or MAIL$_
SEND_FID once, or you can specify MAIL$_SEND_RECORD one or more
times.
20.6 – Condition Values Returned
SS$_NORMAL Normal successful completion.
MAIL$_CONITMCOD The specified item codes define conflicting
operations.
MAIL$_INVITMCOD The specified item code is invalid.
MAIL$_INVITMLEN The specified item length is invalid.
MAIL$_MISREQITEM The required item is missing.
MAIL$_OPENIN The required file is missing.
SS$_ACCVIO Access violation.
21 – MAIL$SEND_BEGIN
Initiates processing to send a message to the users on the
address list. You must call MAIL$SEND_BEGIN before you call any
other send routine.
Format
MAIL$SEND_BEGIN context ,in_item_list ,out_item_list
21.1 – 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.
21.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Send context information to be passed to other send routines. The
context argument is the address of a longword that contains send
context information.
You should specify the value of this argument as 0 in the first
of a sequence of calls to send routines. In subsequent calls, you
should specify the send 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.
21.3 – Input Item Codes
MAIL$_SEND_PERS_NAME MAIL$_SEND_NO_PERS_NAME
Note that you must specify only one of these item codes. An error
is generated if you specify both item codes. MAIL$_SEND_PERS_
NAME specifies the personal name text to be used in the message
header. The buffer address field of the item descriptor points
to a buffer that contains a character string 0 to 127 characters
long.
Specify a value from 0 to 127 in the buffer length field of the
item descriptor.
The Boolean item code MAIL$_SEND_NO_PERS_NAME specifies that no
personal name string be used during message construction.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_SEND_SIGFILE MAIL$_SEND_NO_SIGFILE
Note that you must specify only one of these item codes. An
error is generated if you specify both item codes. MAIL$_
SEND_SIGFILE specifies the full OpenVMS file specification
of the signature file to be used in the message. The default
file specification used for a signature file is the user mail
directory specification and .SIG as the file type. 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 Boolean item code MAIL$_SEND_NO_SIGFILE specifies that no
signature file be used during message construction.
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.
21.4 – Output Item Codes
MAIL$_SEND_COPY_FORWARD
When you specify the Boolean item code MAIL$_SEND_COPY_FORWARD,
MAIL$SEND_BEGIN returns the value of the caller's copy forward
flag as a longword value.
MAIL$_SEND_COPY_SEND
When you specify the Boolean item code MAIL$_SEND_COPY_SEND,
MAIL$SEND_BEGIN returns the value of the caller's copy send flag
as a longword value.
MAIL$_SEND_COPY_REPLY
When you specify the Boolean item code MAIL$_SEND_COPY_REPLY,
MAIL$SEND_BEGIN returns the value of the caller's copy reply flag
as a longword value.
MAIL$_SEND_USER
When you specify MAIL$_SEND_USER, MAIL$SEND_BEGIN returns the
process owner's user name. 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.
21.5 – Description
MAIL$SEND_BEGIN creates and initializes a send context for
subsequent calls to send routines.
21.6 – Condition Values Returned
SS$_NORMAL Normal successful completion.
MAIL$_CODERR Internal system error.
MAIL$_CONITMCOD The specified item codes perform conflicting
operations.
MAIL$_ILLPERNAME The specified personal name string 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.
SS$_ACCVIO Access violation.
Any condition values returned by $GETJPIW, LIB$FREE_VM, and
LIB$GET_VM.
22 – MAIL$SEND_END
Terminates send processing.
Format
MAIL$SEND_END context ,in_item_list ,out_item_list
22.1 – 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.
22.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Send context information to be passed to send routines. The
context argument is the address of a longword that contains send
context information returned by MAIL$SEND_BEGIN.
If send processing is successfully terminated, the value of the
context argument is changed 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. This routine does
not use the in_item_list argument.
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. This routine does not use the out_item_list argument.
22.3 – Description
The MAIL$SEND_END routine deallocates the send context as well as
any dynamic memory allocated by previous send routine calls.
22.4 – 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.
23 – MAIL$SEND_MESSAGE
Begins the actual sending of the message after the message has
been constructed.
Format
MAIL$SEND_MESSAGE context ,in_item_list ,out_item_list
23.1 – 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.
23.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Send context information to be passed to send routines. The
context argument is the address of a longword that contains send
context information returned by MAIL$SEND_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.
23.3 – Input Item Codes
MAIL$_SEND_ERROR_ENTRY
MAIL$_SEND_ERROR_ENTRY specifies the longword address of an entry
point to process errors during a send operation. The descriptor
of the recipient that failed, the address of the signal array,
and the user-specified data are passed as input to the routine.
Refer to the VSI OpenVMS Programming Concepts Manual for more
information about the signal array and its use by condition-
handling routines.
MAIL$_SEND_RECIP_FOLDER
MAIL$_SEND_RECIP_FOLDER specifies the descriptor of a recipient's
folder name. If you do not specify the MAIL$_SEND_RECIP_FOLDER
item code, the mail will be sent to the default NEWMAIL folder. A
valid folder name can be 1 to 39 characters in length.
MAIL$_SEND_SUCCESS_ENTRY
MAIL$_SEND_SUCCESS_ENTRY specifies the longword address of an
entry point to process successes during a send operation. The
descriptor of the recipient that succeeded, the address of the
signal array, and the user-specified data are passed as input
to the routine. Refer to the VSI OpenVMS Programming Concepts
Manual for more information about the signal array and its use by
condition-handling routines.
MAIL$_SEND_USER_DATA
MAIL$_SEND_USER_DATA specifies a longword that MAIL$SEND_MESSAGE
passes to the SEND action routines.
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.
23.4 – Output Item Codes
None.
23.5 – Description
The MAIL$SEND_MESSAGE routine sends a message built with the
MAIL$SEND_ADD_BODYPART routine to every user on the address
list. If you have not used MAIL$SEND_ADD_BODYPART to construct
a message, MAIL$SEND_MESSAGE sends only a message header.
If MAIL$SEND_MESSAGE encounters errors sending to an addressee,
it calls the routine specified by MAIL$_SEND_ERROR_ENTRY.
Otherwise, it calls the routine specified by MAIL$_SEND_SUCCESS_
ENTRY.
If either routine is not specified, MAIL$SEND_MESSAGE calls no
other routines.
If you specify the MAIL$_SEND_RECIP_FOLDER item code, the mail
is placed in the specified folder. Otherwise, the mail is sent to
the default NEWMAIL folder.
23.6 – 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.
SS$_ACCVIO Access violation.
Any condition value returned by $CONNECT.
24 – MAIL$USER_BEGIN
Initiates access to the Mail common user database. You must call
MAIL$USER_BEGIN before you call any other user routines.
Format
MAIL$USER_BEGIN context ,in_item_list ,out_item_list
24.1 – 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.
24.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
User context information to be passed to other user routines. The
context argument is the address of a longword that contains user
context information.
You should specify the value of this argument as 0 in the first
of a sequence of calls to MAIL routines. In following calls, you
should specify the user 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. This routine does
not use the in_item_list argument.
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.
24.3 – Output Item Codes
MAIL$_USER_AUTO_PURGE
When you specify the Boolean item code MAIL$_USER_AUTO_PURGE,
MAIL$USER_BEGIN returns the value of the automatic purge mail
flag as a longword value.
MAIL$_USER_CAPTIVE
When you specify the Boolean item code MAIL$_USER_CAPTIVE,
MAIL$USER_BEGIN returns the value of the UAF CAPTIVE flag as a
longword value.
MAIL$_USER_CC_PROMPT
When you specify the Boolean item code MAIL$_USER_CC_PROMPT,
MAIL$USER_BEGIN returns the value of the cc prompt flag as a
longword value.
MAIL$_USER_COPY_FORWARD
When you specify the Boolean item code MAIL$_USER_COPY_FORWARD,
MAIL$USER_BEGIN returns the value of the copy self forward flag
as a longword value.
MAIL$_USER_COPY_REPLY
When you specify the Boolean item code MAIL$_USER_COPY_REPLY,
MAIL$USER_BEGIN returns the value of the copy self reply flag as
a longword value.
MAIL$_USER_COPY_SEND
When you specify the Boolean item code MAIL$_USER_COPY_SEND,
MAIL$USER_BEGIN returns the value of the copy self send flag as a
longword value.
MAIL$_USER_FORWARDING
When you specify MAIL$_USER_FORWARDING, MAIL$USER_BEGIN returns
the forwarding address string. 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$_USER_FORM
When you specify MAIL$_USER_FORM, MAIL$USER_BEGIN returns the
default print form string. 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$_USER_FULL_DIRECTORY
When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_BEGIN
returns complete directory path of the MAIL subdirectory. 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$_USER_NEW_MESSAGES
When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_BEGIN returns
the new message count. The buffer address field of the item
descriptor points to a word that receives the new message count.
MAIL$_USER_PERSONAL_NAME
When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_BEGIN
returns the personal name string. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 127 characters long.
Specify a value from 0 to 127 in the buffer length field of the
item descriptor.
MAIL$_USER_QUEUE
When you specify MAIL$_USER_QUEUE, MAIL$USER_BEGIN returns the
default print queue name. 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$_USER_RETURN_USERNAME
When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_BEGIN
returns the user name string. 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$_USER_SIGFILE
When you specify MAIL$_USER_SIGFILE, MAIL$USER_BEGIN returns the
default signature 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$_USER_SUB_DIRECTORY
When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_BEGIN
returns the subdirectory 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.
24.4 – Description
MAIL$USER_BEGIN creates and initializes a user database context
for subsequent calls to other user routines.
24.5 – 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.
25 – MAIL$USER_DELETE_INFO
Removes a record from the user profile database.
Format
MAIL$USER_DELETE_INFO context ,in_item_list ,out_item_list
25.1 – 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.
25.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
User context information to be passed to send routines. The
context argument is the address of a longword that contains user
context information returned by MAIL$USER_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 must include at least one device item descriptor.
The item list is terminated by longword value of 0.
25.3 – Input Item Codes
MAIL$_USER_USERNAME
MAIL$_USER_USERNAME specifies the record to be deleted from
the user profile database. The buffer address field of the item
descriptor points to a buffer that contains the user name string
encoded in a character string 0 to 31 characters long.
Specify a value from 0 to 31 in the buffer length field of the
item descriptor.
Setting bit 4 of DCL_CTLFLAGS, enables the user name string
encoded in a character string 0 to 255 characters long.
NOTE
Once this bit is set, user name length is set to a maximum
of 255 characters long. Even if this bit is cleared, the
behavior remains unchanged, that is, supports user name
length of 255 characters long, but there is no way to reset
it to 31 characters long.
The item code MAIL$_USER_USERNAME 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.
25.4 – Output Item Codes
None.
25.5 – Description
To delete a record from the user profile database, you must have
SYSPRV privilege.
25.6 – 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.
MAIL$_NOSUCHUSR The specified user name is not valid.
MAIL$_NOSYSPRV The operation requires the SYSPRV privilege.
SS$_ACCVIO Access violation.
26 – MAIL$USER_END
Terminates access to the user profile database.
Format
MAIL$USER_END context ,in_item_list ,out_item_list
26.1 – 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.
26.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
User context information to be passed to user routines. The
context argument is the address of a longword that contains user
context information.
If the Mail utility terminates access to the user profile
database successfully, the value of the argument context is
changed 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. This routine does
not use the in_item_list argument.
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. This routine does not use the out_item_list argument.
26.3 – Description
The MAIL$USER_END routine deallocates the user database context
created by MAIL$USER_BEGIN as well as all dynamic memory
allocated by previous user routines.
26.4 – 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.
27 – MAIL$USER_GET_INFO
Obtains information about a user from the user profile database.
Format
MAIL$USER_GET_INFO context ,in_item_list ,out_item_list
27.1 – 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.
27.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
User context information to be passed to user routines. The
context argument is the address of a longword that contains user
context information returned by MAIL$USER_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 must include at least one device item descriptor.
The item list is terminated by longword value of 0.
27.3 – Input Item Codes
MAIL$_USER_FIRST
The Boolean item code MAIL$_USER_FIRST specifies that MAIL$USER_
GET_INFO return information in the user profile about the first
entry in the user profile database.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_USER_
USERNAME in the same call to MAIL$USER_GET_INFO.
MAIL$_USER_NEXT
The Boolean item code MAIL$_USER_NEXT specifies that MAIL$USER_
GET_INFO return information in the user profile about the next
user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_USER_
USERNAME in the same call to MAIL$USER_GET_INFO.
MAIL$_USER_USERNAME
The item code MAIL$_USER_USERNAME points to the username string.
Specify the address of the username string in the buffer address
field and specify the length of the username string in the buffer
length field of the item descriptor.
Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT and MAIL$_USER_
USERNAME in the same call to MAIL$USER_GET_INFO.
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.
27.4 – Output Item Codes
MAIL$_USER_AUTO_PURGE
When you specify the Boolean item code MAIL$_USER_AUTO_PURGE,
MAIL$USER_GET_INFO returns the value of the automatic purge mail
flag as a longword value.
MAIL$_USER_CC_PROMPT
When you specify the Boolean item code MAIL$_USER_CC_PROMPT,
MAIL$USER_GET_INFO returns the value of the cc prompt flag as a
longword value.
MAIL$_USER_COPY_FORWARD
When you specify the Boolean item code MAIL$_USER_COPY_FORWARD,
MAIL$USER_GET_INFO returns the value of the copy self forward
mail flag as a longword value.
MAIL$_USER_COPY_REPLY
When you specify the Boolean item code MAIL$_USER_COPY_REPLY,
MAIL$USER_GET_INFO returns the value of the copy self reply mail
flag as a longword value.
MAIL$_USER_COPY_SEND
When you specify the Boolean item code MAIL$_USER_COPY_SEND,
MAIL$USER_GET_INFO returns the value of the copy self send mail
flag as a longword value.
MAIL$_USER_EDITOR
When you specify MAIL$_USER_EDITOR, MAIL$USER_GET_INFO returns
the name of the default editor. 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$_USER_FORWARDING
When you specify MAIL$_USER_FORWARDING, MAIL$USER_GET_INFO
returns the forwarding address. 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$_USER_FORM
When you specify MAIL$_USER_FORM, MAIL$USER_GET_INFO returns the
default print form string. 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$_USER_FULL_DIRECTORY
When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_GET_INFO
returns the complete directory path of the MAIL subdirectory
string. 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$_USER_NEW_MESSAGES
When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_GET_INFO
returns the new messages count. The buffer address field of the
item descriptor points to a word that receives the new message
count as a word value.
MAIL$_USER_PERSONAL_NAME
When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_GET_INFO
returns the personal name string. The buffer address field of
the item descriptor points to a buffer that receives a character
string 0 to 127 characters long.
Specify a value from 0 to 127 in the buffer length field of the
item descriptor.
MAIL$_USER_QUEUE
When you specify MAIL$_USER_QUEUE, MAIL$USER_GET_INFO returns
the default print queue name string. 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$_USER_RETURN_USERNAME
When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_GET_INFO
returns the user name. 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$_USER_SIGFILE
When you specify MAIL$_USER_SIGFILE, MAIL$USER_GET_INFO returns
the default signature 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$_USER_SUB_DIRECTORY
When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_GET_INFO
returns the MAIL subdirectory specification string. 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.
27.5 – Description
The MAIL$USER_GET_INFO routine returns information about
specified entries in the user profile database. If you do not
specify a user name, MAIL$USER_GET_INFO returns information about
the user name associated with the calling process. To obtain
information about a user name other than that associated with the
calling process, you need the SYSNAM privilege.
27.6 – Condition Values Returned
SS$_NORMAL Normal successful completion.
MAIL$_CONITMCOD The specified item codes perform conflicting
operations.
MAIL$_INVITMCOD The specified item code is invalid.
MAIL$_INVITMLEN The specified item length is invalid.
MAIL$_MISREQITEM The required item is missing.
MAIL$_NOSUCHUSR The specified user name is invalid.
MAIL$_NOSYSPRV The specified operation requires the SYSPRV
privilege.
SS$_ACCVIO Access violation.
28 – MAIL$USER_SET_INFO
Adds or modifies a specified user record in the user profile
database.
Format
MAIL$USER_SET_INFO context ,in_item_list ,out_item_list
28.1 – 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.
28.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
User context information to be passed to user routines. The
context argument is the address of a longword that contains user
context information returned by MAIL$USER_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 must include at least one device item descriptor.
The item list is terminated by longword value of 0.
28.3 – Input Item Codes
MAIL$_USER_CREATE_IF
The Boolean item code MAIL$_USER_CREATE_IF specifies that
MAIL$USER_SET_INFO should create the record for the specified
user if it does not already exist.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_AUTO_PURGE
The Boolean item codes MAIL$_USER_SET_AUTO_PURGE and MAIL$_
USER_SET_NO_AUTO_PURGE set and clear the auto purge flag for
the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_CC_PROMPT
The Boolean item codes MAIL$_USER_SET_CC_PROMPT and MAIL$_
USER_SET_NO_CC_PROMPT set and clear the cc prompt flag for the
specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_COPY_FORWARD
The Boolean item codes MAIL$_USER_SET_COPY_FORWARD and MAIL$_
USER_SET_NO_COPY_FORWARD set and clear the copy self forward flag
for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_COPY_REPLY
The Boolean item codes MAIL$_USER_SET_COPY_REPLY and MAIL$_USER_
SET_NO_COPY_REPLY set and clear the copy self reply flag for the
specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_COPY_SEND
The Boolean item codes MAIL$_USER_SET_COPY_SEND and MAIL$_USER_
SET_NO_COPY_SEND set and clear the copy self send flag for the
specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_EDITOR
MAIL$_USER_SET_EDITOR specifies the name of a default editor to
be used by the specified user. 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 Boolean item code MAIL$_USER_SET_NO_EDITOR clears the default
editor field for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_FORM
MAIL$_USER_SET_FORM specifies the default print form string
for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_FORM clears the default
print form field for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_FORWARDING
MAIL$_USER_SET_FORWARDING specifies a forwarding address string
for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_FORWARDING clears the
forwarding address field for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_NEW_MESSAGES
MAIL$_USER_SET_NEW_MESSAGES specifies the new message count
for the specified user. The buffer address field of the item
descriptor points to a word that contains the new number of new
messages.
MAIL$_USER_SET_PERSONAL_NAME
MAIL$_USER_SET_PERSONAL_NAME specifies a personal name string
for the specified user. The buffer address field of the item
descriptor points to a buffer that contains a character string 0
to 127 characters long.
Specify a value from 0 to 127 in the buffer length field of the
item descriptor.
The Boolean item code MAIL$_USER_SET_NO_PERSONAL_NAME clears the
personal field for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_QUEUE
MAIL$_USER_SET_QUEUE specifies a default print queue name string
for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_QUEUE clears the default
print queue field for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_SIGFILE
MAIL$_USER_SET_SIGFILE specifies a signature file specification
for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_SIGFILE clears the
signature file field for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_SET_SUB_DIRECTORY
MAIL$_USER_SET_SUB_DIRECTORY specifies a MAIL subdirectory. 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 Boolean item code MAIL$_USER_SET_NO_SUB_DIRECTORY disables
the use of a MAIL subdirectory for the specified user.
Specify the value 0 in the buffer length and buffer address
fields of the item descriptor.
MAIL$_USER_USERNAME
MAIL$_USER_USERNAME specifies the record to be modified in the
user profile database and points to the user name string. The
buffer address field of the item descriptor points to a buffer
that contains a character string 0 to 31 characters long.
Specify a value from 0 to 31 in the buffer length field of the
item descriptor.
Setting bit 4 of DCL_CTLFLAGS, enables the user name string
encoded in a character string 0 to 255 characters long.
NOTE
Once this bit is set, user name length is set to a maximum
of 255 characters long. Even if this bit is cleared, the
behavior remains unchanged, that is, supports user name
length of 255 characters long, but there is no way to reset
it to 31 characters long.
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.
28.4 – Output Item Codes
None.
28.5 – Description
The MAIL$USER_SET_INFO routine modifies specified records in
the user profile database. If you do not specify a user name,
the routine modifies the user record associated with the calling
process.
To modify any user record other than that associated with the
calling process, you must have SYSPRV privilege. However, if
you want to add or modify only the forwarding address of another
user, SYSNAM privilege is sufficient.
28.6 – Condition Values Returned
SS$_NORMAL Normal successful completion.
MAIL$_CONITMCOD The specified item codes perform conflicting
operations.
MAIL$_ILLCHAR Unacceptable character in personal name.
Utility returns three formatted ASCII
output (FAO) arguments including the illegal
character, the length of the string, and the
string address.
MAIL$_ILLPERNAM Personal name formatted improperly. Returns
an FAO argument containing the improperly
formatted personal name.
MAIL$_ILLSUBDIR Illegal subdirectory specification. Returns
an FAO argument containing the subdirectory
string.
MAIL$_INVITMCOD The specified item code is invalid.
MAIL$_INVITMLEN The specified item length is invalid.
MAIL$_MISREQITEM The required item is missing.
MAIL$_NAMTOOBIG Specified name exceeds 255-character limit.
MAIL$_NOTSUBDIR No such subdirectory. Returns an FAO argument
containing the subdirectory string.
MAIL$_NOSUCHUSR No such user. Returns the name of the unfound
user.
MAIL$_NOSYSNAM Caller needs SYSNAM privileges.
MAIL$_NOSYSPRV Caller needs system privileges.
SS$_ACCVIO Access violation.