 |
OpenVMS Utility Routines Manual
MAIL$SEND_ADD_BODYPART
Builds the body of a message.
Format
MAIL$SEND_ADD_BODYPART 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.
See MAIL$SEND_BEGIN for a description of an input item descriptor.
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 255 characters long.
Specify a value from 0 to 255 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:
- MAIL$_SEND_FID
- 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.
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.
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.
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.
|
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
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 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.
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.
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.
Description
MAIL$SEND_BEGIN creates and initializes a send context for subsequent
calls to send routines.
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.
|
MAIL$SEND_END
Terminates send processing.
Format
MAIL$SEND_END context ,in_item_list ,out_item_list
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Longword condition value. All utility routines return a condition value
in R0. Condition values that can be returned by this routine are listed
under Condition Values Returned.
Arguments
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
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.
Description
The MAIL$SEND_END routine deallocates the send context as well as any
dynamic memory allocated by previous send routine calls.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion
|
|
MAIL$_INVITMCOD
|
The specified item code is invalid.
|
|
MAIL$_INVITMLEN
|
The specified item length is invalid.
|
|
MAIL$_MISREQITEM
|
The required item is missing.
|
|
SS$_ACCVIO
|
Access violation.
|
|
Any condition value returned by LIB$FREE_VM.
|
MAIL$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
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_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
OpenVMS Programming Concepts Manual for more information about the signal array and its use
by condition-handling routines.
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
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.
Output Item Codes
None.
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.
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.
|
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
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 |
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.
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.
|
