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.