OpenVMS Utility Routines Manual
MAIL$MESSAGE_MODIFY
Modifies information in the message header.
Format
MAIL$MESSAGE_MODIFY context ,in_item_list ,out_item_list
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Longword condition value. All utility routines return a condition value
in R0. Condition values that can be returned by this routine are listed
under Condition Values Returned.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
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.
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:
- MAIL$V_replied
- 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.
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.
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.
|
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
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Longword condition value. All utility routines return a condition value
in R0. Condition values that can be returned by this routine are listed
under Condition Values Returned.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Message context information to be passed to message routines. The
context argument is the address of a longword that
contains message context information returned by MAIL$MESSAGE_BEGIN.
in_item_list
| OpenVMS usage: |
itmlst_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying options for the routine. The
in_item_list argument is the address of a list of item
descriptors, each of which specifies an option and provides the
information needed to perform the operation.
The item list is terminated by longword value of 0.
Input Item Codes
MAIL$_MESSAGE_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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 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.
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.
Description
MAIL$MESSAGE_SELECT deselects previously selected messages whether or
not you request a valid selection.
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.
|
MAIL$SEND_ABORT
Cancels a currently executing send operation.
Format
MAIL$SEND_ABORT context ,in_item_list ,out_item_list
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Longword condition value. All utility routines return a condition value
in R0. Condition values that can be returned by this routine are listed
under Condition Value Returned.
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.
Description
MAIL$SEND_ABORT is useful when, for example, the user presses Ctrl/C
during the execution of MAIL$SEND_MESSSAGE.
Condition Value Returned
|
SS$_NORMAL
|
Normal successful completion.
|
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
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Longword condition value. All utility routines return a condition value
in R0. Condition values that can be returned by this routine are listed
under Condition Values Returned.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
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.
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:
- User name specified as a To: address (default)
- 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.
Output Item Codes
None.
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.
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.
|
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
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Longword condition value. All utility routines return a condition value
in R0. Condition values that can be returned by this routine are listed
under Condition Values Returned.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
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.
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 255 characters
long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 in the buffer
length field of the item descriptor.
Calls to MAIL$SEND_ADD_ATTRIBUTE using this input item code should 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 255 characters long.
Specify a value from 0 to 255 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 255 characters long.
Specify a value from 0 to 255 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.
Output Item Codes
None.
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).
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.
|
|
