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

    Obtains information about a specified mail file.

    Format

      MAIL$MAILFILE_INFO_FILE  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
    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.

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.

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 - 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.

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.