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

    Selects a message or messages from the currently open mail file.
    Before you attempt to read a message, you must select it.

    Format

      MAIL$MESSAGE_SELECT  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
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information returned by MAIL$MESSAGE_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$_MESSAGE_BEFORE

    When you specify MAIL$_MESSAGE_BEFORE, MAIL$MESSAGE_SELECT
    selects a message received before a specified date and time. The
    buffer address field of the item descriptor points to a buffer
    that contains a character string 0 to 255 characters long in
    absolute time.

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

 MAIL$_MESSAGE_CC_SUBSTRING

    MAIL$_MESSAGE_CC_SUBSTRING specifies a character string that must
    match a substring contained in the CC: field of the specified
    message. If the strings match, the message is selected. 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$_MESSAGE_FLAGS

    MAIL$_MESSAGE_FLAGS specifies bit masks that must be initialized
    to 1.

 MAIL$_MESSAGE_FLAGS_MBZ

    MAIL$_MESSAGE_FLAGS_MBZ specifies Mail system flags that must be
    set to 0.

 MAIL$_MESSAGE_FOLDER

    MAIL$_MESSAGE_FOLDER specifies the name of the folder that
    contains messages to be selected.

    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.

    This item code is required.

 MAIL$_MESSAGE_FROM_SUBSTRING

    MAIL$_MESSAGE_FROM_SUBSTRING specifies a user-specified character
    string that must match the substring contained in the From: field
    of a specified message. If the strings match, the message is
    selected.

    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$_MESSAGE_SINCE

    When you specify MAIL$_MESSAGE_SINCE, the Mail utility selects a
    message received on or after a specified date and time.

    The buffer address field of the item descriptor points to a
    buffer that contains a character string 0 to 255 characters long
    in absolute time.

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

 MAIL$_MESSAGE_TO_SUBSTRING

    MAIL$_MESSAGE_TO_SUBSTRING specifies a user-specified character
    string that must match a substring contained in the To: field
    of a specified message. If the strings match, the message is
    selected.

    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$_MESSAGE_SUBJ_SUBSTRING

    MAIL$_MESSAGE_SUBJ_SUBSTRING specifies a user-specified character
    string that must match a substring contained in the Subject:
    field of a specified message. If the strings match, the message
    is selected.

    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.

 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 Code

 MAIL$_MESSAGE_SELECTED

    When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_SELECT
    returns the number of selected messages as a longword value.

5 - Description

    MAIL$MESSAGE_SELECT deselects previously selected messages
    whether or not you request a valid selection.

6 - Condition Values Returned

    MAIL$_ILLCTXADR    The context block address is illegal.
    MAIL$_INVITMCOD    The specified item code is invalid.
    MAIL$_INVITMLEN    The specified item length is invalid.
    MAIL$_INVQUAVAL    The specified qualifier is invalid
    MAIL$_MISREQITEM   The required item is missing.
    MAIL$_NOFILEOPEN   The mail file is not open.
    MAIL$_NOTEXIST     The specified folder does not exist.
    MAIL$_NOTISAM      The operation applies only to indexed files.
    MAIL$_WRONGCTX     The context block is incorrect.
    MAIL$_WRONGFILE    The specified file is incorrect in this
                       context.
    SS$_ACCVIO         Access violation.
    Any condition value returned by LIB$GET_VM.