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

    Opens a specified mail file for processing. You must use this
    routine to open a mail file before you can do either of the
    following:

    o  Call any mail file routines to manipulate mail files

    o  Call message routines to read messages from the specified mail
       file

    Format

      MAIL$MAILFILE_OPEN  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 file
    specification MAIL$MAILFILE_OPEN should use when opening a mail
    file. The buffer address field points to a character string of 0
    to 255 characters that defines the default 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 the buffer length field of the item
    descriptor, MAIL$MAILFILE_OPEN uses the current default directory
    as the default mail file specification.

    If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_
    OPEN 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_NAME

    MAIL$_MAILFILE_NAME specifies the name of the mail file
    MAIL$MAILFILE_OPEN should open. The buffer address field
    points to a buffer that contains a character string of 0 to 255
    characters.

    Specify a value from 0 to 255 in the buffer length field of the
    item descriptor.

    If you do not MAIL$_MAILFILE_NAME, the default mail file name is
    MAIL.

 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_OPEN
    returns the number of deleted bytes in the specified mail file as
    a longword value.

 MAIL$_MAILFILE_INDEXED

    When you specify MAIL$_MAILFILE_INDEXED, MAIL$MAILFILE_OPEN
    returns a Boolean TRUE when you open an indexed file. The buffer
    length field points to a longword that receives the Boolean
    value.

 MAIL$_MAILFILE_RESULTSPEC

    When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_OPEN
    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_OPEN
    returns the name of the wastebasket for the specified mail file.
    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.

5 - Description

    The default mail file specification is MAIL.MAI in the MAIL
    subdirectory.

6 - Condition Values Returned

    MAIL$_FILEOPEN     The mail file is already open.
    MAIL$_INVITMCOD    The specified item code is invalid.
    MAIL$_INVITMLEN    The specified item length is invalid.
    MAIL$_MISREQITEM   The required item is missing.
    MAIL$_NOMSGS       No messages are available.
    SS$_ACCVIO         Access violation.
    Any condition value returned by LIB$GET_VM, $CONNECT, and $OPEN.