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
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 – 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.
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.
4 – Description
MAIL$USER_BEGIN creates and initializes a user database context
for subsequent calls to other user routines.
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.