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

    Copies messages between files or folders.

    Format

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

    You should specify this argument as 0 in the first of a sequence
    of calls to message routines. In the following calls, you should
    specify the message 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. 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_COPY copies the message preceding the current
    message.

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

    Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and MAIL$_
    MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.

 MAIL$_MESSAGE_DEFAULT_NAME

    MAIL$_MESSAGE_DEFAULT_NAME specifies the default file
    specification of a mail file to open in order to copy a message.
    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_DELETE

    When you specify the Boolean item code MAIL$_MESSAGE_DELETE,
    MAIL$MESSAGE_COPY deletes the message in the current folder after
    the message has been copied to a destination folder.

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

    Specify MAIL$_MESSAGE_DELETE to emulate the operation of MAIL
    MOVE or FILE command.

 MAIL$_MESSAGE_FILE_ACTION

    MAIL$_MESSAGE_FILE_ACTION specifies the address of the mail
    file action routine called if a mail file is to be created. Two
    parameters are passed as follows:

    o  User data longword

    o  Address of the descriptor of the file name to be created

    The buffer address field of the item descriptor points to a
    longword that denotes a procedure value.

 MAIL$_MESSAGE_FILENAME

    MAIL$_MESSAGE_FILENAME specifies the name of the mail file to
    which the current message will be moved. 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_FOLDER

    MAIL$_MESSAGE_FOLDER specifies the name of the target folder
    for moving mail messages. 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.

    The item code MAIL$_MESSAGE_FOLDER is required.

 MAIL$_MESSAGE_FOLDER_ACTION

    MAIL$_MESSAGE_FOLDER_ACTION specifies the entry point address of
    the folder action routine called if a folder is to be created.
    Two parameters are passed as follows:

    o  User data longword

    o  Address of a descriptor of the folder name to be created.

    The buffer address field of the item descriptor points to a
    longword that specifies a procedure value.

 MAIL$_MESSAGE_ID

    MAIL$_MESSAGE_ID specifies the message identification number of
    the message on which the 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 MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and MAIL$_
    MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.

 MAIL$_MESSAGE_NEXT

    When you specify the Boolean item code MAIL$_MESSAGE_NEXT, the
    Mail utility copies 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 MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and MAIL$_
    MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.

 MAIL$_MESSAGE_USER_DATA

    MAIL$_MESSAGE_USER_DATA specifies data passed to the folder
    action and mail file action routines. The buffer address field
    of the item descriptor points to a user data longword.

    Specify MAIL$_MESSAGE_USER_DATA with the item codes MAIL$_
    MESSAGE_FILE_ACTION and MAIL$_MESSAGE_FOLDER_ACTION only.

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

    When you specify the Boolean item code MAIL$_MESSAGE_FILE_
    CREATED, MAIL$MESSAGE_COPY returns the value of the file created
    flag as longword value.

 MAIL$_MESSAGE_FOLDER_CREATED

    When you specify the Boolean item code MAIL$_MESSAGE_FOLDER_
    CREATED, MAIL$MESSAGE_COPY returns the value of the folder
    created flag as a longword value.

 MAIL$_MESSAGE_RESULTSPEC

    When you specify MAIL$_MESSAGE_RESULTSPEC, MAIL$MESSAGE_COPY
    returns the mail file resultant 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.

5 - Description

    If you do not specify a file name, the routine copies the message
    to another folder in the currently open mail file. The target
    mail file must be an indexed file.

6 - Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    MAIL$_BADVALUE     The specified keyword value is invalid.
    MAIL$_CONITMCOD    The specified item codes define conflicting
                       operations.
    MAIL$_DATIMUSED    The date and time is currently used in the
                       specified file.
    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$_MSGINFO      Informational records are successfully
                       returned.
    MAIL$_MSGTEXT      Text record is successfully returned.
    MAIL$_NOFILEOPEN   The mail file is not open.
    MAIL$_NOMOREREC    No more records can be found.
    MAIL$_NOTREADIN    The operation is invalid; you are not reading
                       a message.
    MAIL$_RECTOBIG     The record is too large for the MAIL buffer.
    MAIL$_WRONGCTX     The context block is incorrect.
    MAIL$_WRONGFILE    The specified file is incorrect in this
                       context.
    SS$_IVDEVNAM       The device name is invalid.
    SS$_ACCVIO         Access violation.
    Any condition value returned by $CONNECT, $CREATE, $OPEN, $WRITE,
    $READ, and $PUT.