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

    Modifies information in the message header.

    Format

      MAIL$MESSAGE_MODIFY  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_BACK

    When you specify the Boolean item code MAIL$_MESSAGE_BACK,
    MAIL$MESSAGE_MODIFY reads the identification number of the
    specified message in order to return the first record in the
    preceding message.

    Specify the value 0 in the buffer length and buffer address
    fields of the item descriptor.

    Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
    ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_
    MODIFY.

 MAIL$_MESSAGE_FLAGS

    MAIL$_MESSAGE_FLAGS specifies system flags for new mail. The
    buffer address field of the item descriptor points to a word that
    contains bit mask offsets. The following offsets can be used to
    modify the 2-byte bit mask:

    o  MAIL$V_replied

    o  MAIL$V_marked

 MAIL$_MESSAGE_ID

    MAIL$_MESSAGE_ID specifies the message identification number of
    the message on which an operation is to be performed. The buffer
    address field of the item descriptor points to a longword that
    contains the message identification number.

    Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
    ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_
    MODIFY.

 MAIL$_MESSAGE_NEXT

    When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
    MAIL$MESSAGE_MODIFY reads the message identification number of
    a message and returns the first record in the message following
    the current message.

    Specify the value 0 in the buffer length and buffer address
    fields of the item descriptor.

    Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_
    ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_
    MODIFY.

 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_CURRENT_ID

    When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_MODIFY
    returns the message identification number of the current message.
    The buffer address field of the item descriptor points to a
    longword that receives the message identification number.

5 - Condition Values Returned

    MAIL$_CONITMCOD    The specified item codes define conflicting
                       operations.
    MAIL$_DELMSG       The message is deleted.
    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$_MISREQITEM   The required item is missing.
    MAIL$_NOFILEOPEN   The mail file is not open.
    MAIL$_NOMOREMSG    No more messages.
    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 $FIND and $UPDATE.