VMS Help MAIL Routines, MAIL$USER_BEGIN  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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.