1 MAIL_Routines The callable interface of the Mail utility (MAIL) lets you send messages to users on your system or on any other computer connected to your system with DECnet. 2 MAIL$MAILFILE_BEGIN Initiates mail file processing. Format MAIL$MAILFILE_BEGIN context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Mail file context information to be passed to other mail file routines. The context argument is the address of a longword that contains mail file context information. You should specify the value of this argument as 0 in the first of a sequence of calls to mail file routines. In the following calls, you should specify the mail file context value returned by this 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 a longword value of 0. For this routine, there are no input item codes. 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. The only output item code for this routine is the MAIL$_MAILFILE_ MAIL_DIRECTORY item code. When you specify MAIL$_MAILFILE_ MAIL_DIRECTORY, MAIL$MAILFILE_BEGIN returns the mail directory specification to the caller. 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_BEGIN creates and initiates a mail file context for calls to other mail file routines. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. Any condition value returned by LIB$GET_VM, $GETJPIW, and $GETSYI. 2 MAIL$MAILFILE_CLOSE Closes the currently open mail file. Format MAIL$MAILFILE_CLOSE context ,in_item_list ,out_item_list 3 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. 3 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_FULL_CLOSE The Boolean item code MAIL$_MAILFILE_FULL_CLOSE specifies that MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it closes the mail file. If the number of bytes deleted by the purge operation exceeds a system-defined threshold, the Mail utility reclaims the deleted space from the mail file. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. The system-defined threshold is reserved by HP . 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. 3 Output_Item_Codes MAIL$_MAILFILE_DATA_RECLAIM When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_CLOSE returns the number of data buckets reclaimed during the reclaim operation as a longword value. MAIL$_MAILFILE_DATA_SCAN When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_CLOSE returns the number of data buckets scanned during the reclaim operation as a longword value. MAIL$_MAILFILE_INDEX_RECLAIM When you specify MAIL$_MAILFILE_INDEX_RECLAIM, MAIL$MAILFILE_ CLOSE returns the number of index buckets reclaimed during a reclaim operation as a longword value. MAIL$_MAILFILE_MESSAGES_DELETED When you specify MAIL$_MAILFILE_MESSAGES_DELETED, MAIL$MAILFILE_ CLOSE returns the number of messages deleted as a longword value. MAIL$_MAILFILE_TOTAL_RECLAIM When you specify MAIL$_MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_ CLOSE returns the number of bytes reclaimed during a reclaim operation as a longword value. 3 Description If you specify the input item code MAIL$_MAILFILE_FULL_CLOSE, this procedure purges the wastebasket folder automatically before it closes the file. If the number of bytes deleted by this procedure exceeds the deleted byte threshold, the system performs a convert/reclaim operation on the file. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. 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 No mail file is open. SS$_ACCVIO Access violation. 2 MAIL$MAILFILE_COMPRESS Compresses a mail file. Format MAIL$MAILFILE_COMPRESS context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Mail file context information to be passed to various 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 the Mail utility should use when opening a mail file. The buffer address field points to a character string 0 to 255 characters long 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 buffer length field of the item descriptor, MAIL$MAILFILE_COMPRESS uses the current default directory as the default mail file specification. If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_ COMPRESS 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_FULL_CLOSE The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that the wastebasket folder be purged and that convert and reclaim operations be performed, if necessary. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_MAILFILE_NAME MAIL$_MAILFILE_NAME specifies the name of a mail file to be opened. The buffer that the buffer address field points to 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 specify 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. 3 Output_Item_Code MAIL$_MAILFILE_RESULTSPEC When you specify MAIL$_MAILFILE_RESULTSPEC, the Mail utility 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. 3 Description If you do not specify an input file, the MAIL$MAILFILE_ COMPRESS routine compresses the currently open Mail file. The MAIL$MAILFILE_COMPRESS routine signals informational messages concerning the phase of the compression. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. MAIL$_NOTISAM The message file is not an indexed file. RMS$_FNF The specified file cannot be found. RMS$_SHR The specified file is not shareable. SS$_ACCVIO Access violation. SS$_IVDEVNAM The specified device name is invalid. Any condition value returned by LIB$FIND_IMAGE_SYMBOL, LIB$RENAME_FILE, $CREATE, $OPEN, $PARSE, and $SEARCH. 2 MAIL$MAILFILE_END Terminates mail file processing. Format MAIL$MAILFILE_END context ,in_item_list ,out_item_list 3 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. 3 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 MAILFILE context information returned by MAIL$MAILFILE_BEGIN. If mail file processing is terminated successfully, the Mail utility sets the value of the argument context to 0. 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_FULL_CLOSE The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that the wastebasket folder be purged and that convert and reclaim operations be performed, if necessary. Specify the value 0 in the buffer length and buffer address fields 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. 3 Output_Item_Codes None. 3 Description The MAIL$MAILFILE_END routine deallocates the mail file context created by MAIL$MAILFILE_BEGIN as well as any dynamic memory allocated by other mail file processing routines. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. Any condition value returned by LIB$FREE_VM. 2 MAIL$MAILFILE_INFO_FILE Obtains information about a specified mail file. Format MAIL$MAILFILE_INFO_FILE context ,in_item_list ,out_item_list 3 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. 3 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 mail file specification MAIL$MAILFILE_INFO_FILE should use when opening a mail file. The buffer address field of the item descriptor points to a character string of 0 to 255 characters that defines the default mail 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 buffer length field of the item descriptor, MAIL$MAILFILE_INFO_FILE uses the current default directory as the default mail file specification. If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_ INFO_FILE 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_FOLDER_ROUTINE MAIL$_MAILFILE_FOLDER_ROUTINE specifies an entry point longword address of a user-written routine that MAIL$MAILFILE_INFO_FILE should use to display folder names. MAIL$MAILFILE_INFO_FILE calls the user-written routine for each folder in the mail file. MAIL$_MAILFILE_NAME MAIL$_MAILFILE_NAME specifies the name of the mail file to be opened. The buffer address field 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. If you do not specify MAIL$_MAILFILE_NAME, the default mail file name is MAIL. MAIL$_MAILFILE_USER_DATA MAIL$_MAILFILE_USER_DATA specifies a longword that MAIL$MAILFILE_ INFO_FILE should pass to the user-defined folder name action routine. This item code is valid only when used with the item code MAIL$_ MAILFILE_FOLDER_ROUTINE. 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. 3 Output_Item_Codes MAIL$_MAILFILE_DELETED_BYTES When you specify MAIL$_MAILFILE_DELETED_BYTES, MAIL$MAILFILE_ INFO_FILE returns the number of deleted bytes in a specified mail file as longword value. MAIL$_MAILFILE_RESULTSPEC When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_INFO_ FILE 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_INFO_ FILE returns the name of the wastebasket folder of the specified mail file. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 39 characters long. Specify a value from 0 to 39 in the buffer length field of the item descriptor. 3 Description If you do not specify an input file, the MAIL$MAILFILE_INFO_FILE returns information about the currently open mail file. Folder Action Routines If you use the item code MAIL$_MAILFILE_FOLDER_ROUTINE to specify a folder name routine, MAIL$MAILFILE_INFO_FILE passes control to a user-specified routine. For example, the folder action routine could display folder names. The user routine must return a 32-bit integer code. If the return code indicates success, the interaction between the user's routine and the callable routine can continue. The folder action routine passes a pointer to the descriptor of a folder name as well as the user data longword. A descriptor of zero length indicates that the MAIL$MAILFILE_INFO_FILE routine has displayed all folder names. If you do not specify the item code MAIL$_MAILFILE_FOLDER_ROUTINE, MAIL$MAILFILE_INFO_FILE does not call any folder action routines. 3 Condition_Values_Returned 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$_NOTISAM The message file is not an indexed file. MAIL$_OPENIN Mail cannot open the file as input. SS$_ACCVIO Access violation. Any condition value returned by $CLOSE, $OPEN, $PARSE, and $SEARCH. 2 MAIL$MAILFILE_MODIFY Modifies the informational record of an indexed mail file, including the mail file name, the default mail file name, and the wastebasket name. Format MAIL$MAILFILE_MODIFY context ,in_item_list ,out_item_list 3 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. 3 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 that the Mail utility should use when opening a mail file. The buffer address field points to a buffer that contains a character string of 0 to 255 characters that defines the default mail 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_MODIFY uses the current default directory as the default mail file specification. If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_ MODIFY 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 that the Mail utility 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 specify MAIL$_MAILFILE_NAME, the default mail file name is MAIL. MAIL$_MAILFILE_WASTEBASKET_NAME MAILFILE_WASTEBASKET_NAME specifies a new folder name for the wastebasket in the specified mail file. The buffer address field points to a buffer that contains a character string of 1 to 39 characters. 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. 3 Output_Item_Code MAIL$_MAILFILE_RESULTSPEC When you specify MAIL$_MAILFILE_RESULTSPEC, the Mail utility returns the resultant mail file specification. The buffer address field points to a buffer that receives a character string from 0 to 255 characters long. Specify a value from 0 to 255 in the buffer length field of the item descriptor. 3 Description If a mail file is not specified, the currently open mail file is used. 3 Condition_Values_Returned MAIL$_ILLFOLNAM The specified folder name 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$_NOTISAM The message file is not an indexed file. MAIL$_OPENIN Mail cannot open the file as input. SS$_ACCVIO Access violation. Any condition value returned by $CLOSE, $FIND, $PUT, and $UPDATE. 2 MAIL$MAILFILE_OPEN 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 3 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. 3 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. 3 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. 3 Description The default mail file specification is MAIL.MAI in the MAIL subdirectory. 3 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. 2 MAIL$MAILFILE_PURGE_WASTE Deletes messages contained in the wastebasket folder of the currently open mail file. Format MAIL$MAILFILE_PURGE_WASTE context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Mail file context information to be passed to other mail file routines. The context argument is the address of a longword that contains mail file context information. 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_RECLAIM The Boolean item code MAIL$_MAILFILE_RECLAIM specifies that MAIL$MAILFILE_PURGE_WASTE purge the wastebasket folder and reclaim deleted space in the mail file. Specify the value 0 in the buffer length field of the item descriptor. MAIL$_MAILFILE_RECLAIM explicitly requests a reclaim operation and overrides the deleted byte's threshold regardless of the number of bytes deleted during a mail file purge operation. 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. 3 Output_Item_Codes MAIL$_MAILFILE_DATA_RECLAIM When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_ PURGE_WASTE returns the number of data buckets reclaimed during the reclaim operation as a longword value. MAIL$_MAILFILE_DATA_SCAN When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_PURGE_ WASTE returns the number of data buckets scanned during the reclaim operation as a longword value. MAIL$_MAILFILE_INDEX_RECLAIM When you specify MAIL$_MAILFILE_INDEX_RECLAIM, the Mail utility returns the number of index buckets reclaimed during a reclaim operation as a longword value. MAIL$_MAILFILE_DELETED_BYTES When you specify MAIL$_MAILFILE_DELETED_BYTES, MAIL$MAILFILE_ PURGE_WASTE returns the number of bytes deleted from the mail file as a longword value. MAIL$_MAILFILE_MESSAGES_DELETED When you specify MAIL$_MAILFILE_MESSAGES_DELETED, MAIL$MAILFILE_ PURGE_WASTE returns the number of deleted messages as a longword value. MAIL$_MAILFILE_TOTAL_RECLAIM When you specify MAIL$_MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_ PURGE_WASTE returns the number of bytes reclaimed due to a reclaim operation as a longword value. 3 Description If you specify the MAIL$_MAILFILE_RECLAIM item descriptor, all the bytes deleted from the mail file by this routine are reclaimed. 3 Condition_Values_Returned MAIL$_NORMAL Normal successful completion. 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 No mail file is currently open. MAIL$_NOTISAM The message file is not an indexed file. SS$_ACCVIO Access violation. 2 MAIL$MESSAGE_BEGIN Begins message processing. You must call this routine before calling any other message routines. Format MAIL$MESSAGE_BEGIN context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Message context information to be passed to various message routines. The context argument is the address of a longword that contains message context information. You should specify the value of 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 this 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_FILE_CTX MAIL$_MESSAGE_FILE_CTX specifies the mail file context received from MAIL$MAILFILE_BEGIN to be passed to the message routines. The buffer address field of the item descriptor points to a longword that contains mail file context information. The item code MAIL$_MESSAGE_FILE_CTX is required. 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. 3 Output_Item_Code MAIL$_MESSAGE_SELECTED When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_BEGIN returns the number of messages selected as a longword value. 3 Description MAIL$MESSAGE_BEGIN creates and initializes a message context for subsequent calls to message routines. 3 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$_MISREQITEM The required item is missing. MAIL$_NOFILEOPEN The mail file is not open. 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 $GET and LIB$GET_VM. 2 MAIL$MESSAGE_COPY Copies messages between files or folders. Format MAIL$MESSAGE_COPY context ,in_item_list ,out_item_list 3 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. 3 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. 3 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. 3 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. 3 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. 2 MAIL$MESSAGE_DELETE Deletes a specified message from the currently selected folder. Format MAIL$MESSAGE_DELETE context ,in_item_list ,out_item_list 3 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. 3 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. 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_ID MAIL$_MESSAGE_ID specifies the message identification number of the message on which the operation is to be performed. The buffer address field points to a longword that contains the message identification number. The item code MAIL$_MESSAGE_ID is required. 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. 3 Output_Item_Codes None. 3 Description When you delete a message from a selected folder, it is moved to the wastebasket folder. You cannot delete a message from the wastebasket folder. You must use the MAIL$MAILFILE_PURGE_WASTE routine to empty the wastebasket folder. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. 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$_WRONGCTX The context block is incorrect. MAIL$_WRONGFILE The specified file is incorrect in this context. SS$_ACCVIO Access violation. 2 MAIL$MESSAGE_END Ends message processing. Format MAIL$MESSAGE_END context ,in_item_list ,out_item_list 3 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. 3 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. If message processing ends successfully, the argument context is changed to 0. in_item_list OpenVMS usage:itmlst_3 type: longword (unsigned) access: read only mechanism: by reference Item list specifying options for the routine. This routine does not use the in_item_list argument. 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. This routine does not use the out_item_list argument. 3 Description The MAIL$MESSAGE_END routine deallocates the message context created by MAIL$MESSAGE_BEGIN as well as any dynamic memory allocated by other message routines. 3 Condition_Values_Returned MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. Any condition value returned by LIB$FREE_VM. 2 MAIL$MESSAGE_GET Retrieves a message from the set of currently selected messages. Format MAIL$MESSAGE_GET context ,in_item_list ,out_item_list 3 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. 3 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_AUTO_NEWMAIL When you specify the Boolean item code MAIL$_MESSAGE_AUTO_ NEWMAIL, MAIL$MESSAGE_GET automatically places a new message in the mail folder as it is read. MAIL$_MESSAGE_AUTO_NEWMAIL is valid only when specified with the item code MAIL$_MESSAGE_ CONTINUE. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_MESSAGE_BACK When you specify the Boolean item code MAIL$_MESSAGE_BACK, MAIL$MESSAGE_GET reads the message identification number of a specified message to return the first record of 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_ CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_GET. MAIL$_MESSAGE_CONTINUE When you specify the Boolean item code MAIL$_MESSAGE_CONTINUE, MAIL$MESSAGE_GET reads the message identification number of a specified message to return the next text record of 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_ CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_GET. MAIL$_MESSAGE_ID MAIL$_MESSAGE_ID specifies the message identification number of a 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_ CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_GET. MAIL$_MESSAGE_NEXT When you specify the Boolean item code MAIL$_MESSAGE_NEXT, MAIL$MESSAGE_GET reads the message identification number of a specified message to return the first record of 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_ CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_GET. 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. 3 Output_Item_Codes MAIL$_MESSAGE_BINARY_DATE When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_GET returns the message arrival date as a quadword binary value. MAIL$_MESSAGE_CC When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_GET returns the CC: field of the current message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_CURRENT_ID When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_GET 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 identifier number. MAIL$_MESSAGE_DATE When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_GET returns the message creation date string. 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_EXTID MAIL$_MESSAGE_EXTID specifies the external message identification number of the current message. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 255 characters long. MAIL$_MESSAGE_FROM When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_GET returns the From: field of the specified message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_RECORD When you specify MAIL$_MESSAGE_RECORD, MAIL$MESSAGE_GET returns a record of the message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_RECORD is valid only when specified with the item code MAIL$_MESSAGE_CONTINUE. Do not specify MAIL$_MESSAGE_RECORD with the following item codes: o MAIL$_MESSAGE_BACK o MAIL$_MESSAGE_ID o MAIL$_MESSAGE_NEXT MAIL$_MESSAGE_RECORD_TYPE When you specify MAIL$_MESSAGE_RECORD_TYPE, MAIL$MESSAGE_ GET returns the record type. A record may be either header information (MAIL$_MESSAGE_HEADER) or text (MAIL$_MESSAGE_TEXT). The buffer address field of the item descriptor points to a word that receives the record type. MAIL$_MESSAGE_RETURN_FLAGS When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_GET returns the Mail system flag for the current message as a 2-byte bit mask value. MAIL$_MESSAGE_SENDER When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_GET returns the name of the sender of the current message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_SIZE When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_GET returns the size in records of the current message as a longword value. MAIL$_MESSAGE_SUBJECT When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_GET returns the Subject: field of the specified message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_TO When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_GET returns the To: field of the specified message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. 3 Description The first time the MAIL$MESSAGE_GET routine is called, the message information is returned for the first requested message, and the status returned is MAIL$_MSGINFO. Subsequent calls to MAIL$MESSAGE_GET with the MAIL$_MESSAGE_CONTINUE item code return the message text records with the status MAIL$_MSGTEXT, until no more records are left, when MAIL$_NOMOREREC is returned. 3 Condition_Values_Returned MAIL$_MSGINFO Informational records are successfully returned. MAIL$_MSGTEXT Text record is successfully 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$_MISREQITEM The required item is missing. 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$_ACCVIO Access violation. Any condition value returned by $FIND and $UPDATE. 2 MAIL$MESSAGE_INFO Obtains information about a specified message contained in the set of currently selected messages. Format MAIL$MESSAGE_INFO context ,in_item_list ,out_item_list 3 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. 3 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 Boolean item code MAIL$_MESSAGE_BACK, MAIL$MESSAGE_INFO reads the identification number of the current message and returns the preceding 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_INFO. 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_INFO. MAIL$_MESSAGE_NEXT When you specify the Boolean item code MAIL$_MESSAGE_NEXT, MAIL$MESSAGE_INFO reads the message identification number of the current message and returns the message that follows it. 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_INFO. 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. 3 Output_Item_Codes MAIL$_MESSAGE_BINARY_DATE When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_INFO returns the message arrival date as a quadword binary value. MAIL$_MESSAGE_CC When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_INFO returns the CC: field of the current message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_CURRENT_ID When you specify MAIL$_MESSAGE_ID, MAIL$MESSAGE_INFO 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 of the current message. MAIL$_MESSAGE_DATE When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_INFO returns the message creation date string. 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_EXTID When you specify MAIL$_MESSAGE_EXTID, MAIL$MESSAGE_INFO returns the external identification number of the current message as a string. 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_FROM When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_INFO returns the From: field of the specified message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_REPLY_PATH When you specify MAIL$_MESSAGE_REPLY_PATH, MAIL$MESSAGE_INFO returns the reply path of the specified message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_RETURN_FLAGS When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_INFO returns the Mail system flag values for the current message as a 2-byte bit mask value. MAIL$_MESSAGE_SENDER When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_INFO returns the name of the sender of the current message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_SIZE When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_INFO returns the size of the current message in records as a longword value. MAIL$_MESSAGE_SUBJECT When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_INFO returns the Subject: field of the specified message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_MESSAGE_TO When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_INFO returns the To: field of the specified message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. 3 Description MAIL$MESSAGE_INFO obtains information about a particular message. MAIL$MESSAGE_GET retrieves a message from the set of currently selected messages. The first call to MAIL$MESSAGE_GET passes control to MAIL$MESSAGE_INFO. Subsequent calls that include the MAIL$_ MESSAGE_CONTINUE item code return text records. 3 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 LIB$GET_VM. 2 MAIL$MESSAGE_MODIFY Modifies information in the message header. Format MAIL$MESSAGE_MODIFY context ,in_item_list ,out_item_list 3 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. 3 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. 3 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. 3 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. 2 MAIL$MESSAGE_SELECT 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 3 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. 3 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 998 characters long. Specify a value from 0 to 998 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 998 characters long. Specify a value from 0 to 998 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 998 characters long. Specify a value from 0 to 998 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 998 characters long. Specify a value from 0 to 998 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. 3 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. 3 Description MAIL$MESSAGE_SELECT deselects previously selected messages whether or not you request a valid selection. 3 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. 2 MAIL$SEND_ABORT Cancels a currently executing send operation. Format MAIL$SEND_ABORT context ,in_item_list ,out_item_list 3 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 Value Returned. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_BEGIN. in_item_list OpenVMS usage:itmlst_3 type: longword (unsigned) access: read only mechanism: by reference Item list specifying options for the routine. This routine does not use the in_item_list argument. 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. This routine does not use the out_item_list argument. 3 Description MAIL$SEND_ABORT is useful when, for example, the user presses Ctrl/C during the execution of MAIL$SEND_MESSSAGE. 3 Condition_Value_Returned SS$_NORMAL Normal successful completion. 2 MAIL$SEND_ADD_ADDRESS Adds an address to the address list. If an address list does not exist, MAIL$SEND_ADD_ADDRESS creates one. Format MAIL$SEND_ADD_ADDRESS context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_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$_SEND_USERNAME MAIL$_SEND_USERNAME specifies that the Mail utility add a specified user name to the address list. 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. The item code MAIL$_SEND_USERNAME is required. MAIL$_SEND_USERNAME_TYPE MAIL$_SEND_USERNAME_TYPE specifies the type of user name added to the address list. The buffer address field of the item descriptor points to a word that contains the user name type. There are two types of user names, as follows: o User name specified as a To: address (default) o User name specified as a CC: address NOTE Currently, the symbols MAIL$_TO and MAIL$_CC define user name types. 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. 3 Output_Item_Codes None. 3 Description If you do not specify a MAIL$_SEND_USERNAME_TYPE, MAIL$SEND_ADD_ ADDRESS uses MAIL$_TO. You can specify only one user name per call to MAIL$SEND_ADD_ADDRESS. 3 Condition_Values_Returned MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. Any condition values returned by LIB$TPARSE. 2 MAIL$SEND_ADD_ATTRIBUTE Adds an attribute, such as Subject or To, to the message you are currently constructing. Format MAIL$SEND_ADD_ATTRIBUTE context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_BEGIN. You should specify this argument as 0 in the first of a sequence of calls to MAIL routines. In following calls, you should specify the Send 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$_SEND_CC_LINE MAIL$_SEND_CC_LINE specifies a descriptor of the CC: field text. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_SEND_FROM_LINE MAIL$_SEND_FROM_LINE specifies a descriptor of the From: field text of the message to be sent. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. Calls to MAIL$SEND_ADD_ATTRIBUTE using this input item code must be made before any calls to MAIL$SEND_ADD_ADDRESS. The SYSPRV privilege is required to alter the From: of a message. MAIL$_SEND_SUBJECT MAIL$_SEND_SUBJECT specifies a descriptor of the Subject: field text of a message to be sent. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. MAIL$_SEND_TO_LINE MAIL$_SEND_TO_LINE specifies a descriptor of the To: field text of the message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 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. 3 Output_Item_Codes None. 3 Description If you do not specify a To: line, the Mail utility supplies a To: line composed of user names on the To: address list. If you do not specify a CC: line, the Mail utility supplies a CC: line composed of user names on the CC: address list. In either of the above cases, commas separate the user names. To add a message's From: field, you must have the SYSPRV privilege, and the Mail DECnet object must have the SYSPRV privilege on OUTGOING CONNECT (users can set the DECnet object privileges at their discretion). 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. 2 MAIL$SEND_ADD_BODYPART Builds the body of a message. Format MAIL$SEND_ADD_BODYPART context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_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. See MAIL$SEND_BEGIN for a description of an input item descriptor. 3 Input_Item_Codes MAIL$_SEND_DEFAULT_NAME MAIL$_SEND_DEFAULT_NAME specifies the default file specification of a text file to be opened. 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$_SEND_FID MAIL$_SEND_FID specifies the file identifier of the text file to be opened. The buffer address field of the item descriptor points to a buffer that contains the file identifier. To identify a file using a file identifier, you must also specify the device identifier for the file. Specify the device identifier using the MAIL$_SEND_DEFAULT_NAME item code. More information about using a file ID for specifying files can be found in OpenVMS Record Management Services Reference Manual. Note that the MAIL$_SEND_ FID item code and the MAIL$_SEND_FILENAME item code are mutually exclusive. MAIL$_SEND_FILENAME MAIL$_SEND_FILENAME specifies the input file specification of the text file to be opened. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 255 characters long. Note that the MAIL$_SEND_FILENAME item code and the MAIL$_SEND_FID item code are mutually exclusive. Specify a value from 0 to 255 in the buffer length field of the item descriptor. MAIL$_SEND_RECORD MAIL$_SEND_RECORD specifies a descriptor of a text record to be added to the body of the message. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 998 characters long. Specify a value from 0 to 998 in the buffer length field of the item descriptor. When creating a message, do not specify MAIL$_SEND_RECORD in the same call (or series of calls) to MAIL$SEND_ADD_BODYPART with the following item codes: o MAIL$_SEND_FID o MAIL$_SEND_FILENAME NOTE Do not use the MAIL$_SEND_RECORD item code with the MAIL$SEND_ADD_BODYPART routine called from a detached process. The routine creates a temporary file in SYS$SCRATCH that is inaccessible to the detached process. 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. 3 Output_Item_Code MAIL$_SEND_RESULTSPEC When you specify MAIL$_SEND_RESULTSPEC, MAIL$SEND_ADD_BODYPART returns the resultant file specification identified with MAIL$_ SEND_FILENAME. 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. 3 Description You can use MAIL$SEND_ADD_BODYPART to specify a file that contains the entire message or to add a single record to a message. If the message is contained in a file, you call MAIL$SEND_ADD_BODYPART once, specifying the file name. If you want to add to the message record-by-record, you can call MAIL$SEND_ADD_BODYPART repeatedly, specifying a different record each time until you complete the message. You cannot specify both a file name and a record for the same message. You can specify either MAIL$_SEND_FILENAME or MAIL$_ SEND_FID once, or you can specify MAIL$_SEND_RECORD one or more times. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_CONITMCOD The specified item codes define conflicting operations. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. MAIL$_OPENIN The required file is missing. SS$_ACCVIO Access violation. 2 MAIL$SEND_BEGIN Initiates processing to send a message to the users on the address list. You must call MAIL$SEND_BEGIN before you call any other send routine. Format MAIL$SEND_BEGIN context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Send context information to be passed to other send routines. The context argument is the address of a longword that contains send context information. You should specify the value of this argument as 0 in the first of a sequence of calls to send routines. In subsequent calls, you should specify the send context value returned by this 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$_SEND_PERS_NAME MAIL$_SEND_NO_PERS_NAME Note that you must specify only one of these item codes. An error is generated if you specify both item codes. MAIL$_SEND_PERS_ NAME specifies the personal name text to be used in the message header. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 127 characters long. Specify a value from 0 to 127 in the buffer length field of the item descriptor. The Boolean item code MAIL$_SEND_NO_PERS_NAME specifies that no personal name string be used during message construction. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_SEND_SIGFILE MAIL$_SEND_NO_SIGFILE Note that you must specify only one of these item codes. An error is generated if you specify both item codes. MAIL$_ SEND_SIGFILE specifies the full OpenVMS file specification of the signature file to be used in the message. The default file specification used for a signature file is the user mail directory specification and .SIG as the file type. 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 Boolean item code MAIL$_SEND_NO_SIGFILE specifies that no signature file be used during message construction. Specify the value 0 in the buffer length and buffer address fields 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. 3 Output_Item_Codes MAIL$_SEND_COPY_FORWARD When you specify the Boolean item code MAIL$_SEND_COPY_FORWARD, MAIL$SEND_BEGIN returns the value of the caller's copy forward flag as a longword value. MAIL$_SEND_COPY_SEND When you specify the Boolean item code MAIL$_SEND_COPY_SEND, MAIL$SEND_BEGIN returns the value of the caller's copy send flag as a longword value. MAIL$_SEND_COPY_REPLY When you specify the Boolean item code MAIL$_SEND_COPY_REPLY, MAIL$SEND_BEGIN returns the value of the caller's copy reply flag as a longword value. MAIL$_SEND_USER When you specify MAIL$_SEND_USER, MAIL$SEND_BEGIN returns the process owner's user name. 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. 3 Description MAIL$SEND_BEGIN creates and initializes a send context for subsequent calls to send routines. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_CODERR Internal system error. MAIL$_CONITMCOD The specified item codes perform conflicting operations. MAIL$_ILLPERNAME The specified personal name string 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. SS$_ACCVIO Access violation. Any condition values returned by $GETJPIW, LIB$FREE_VM, and LIB$GET_VM. 2 MAIL$SEND_END Terminates send processing. Format MAIL$SEND_END context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_BEGIN. If send processing is successfully terminated, the value of the context argument is changed to 0. in_item_list OpenVMS usage:itmlst_3 type: longword (unsigned) access: read only mechanism: by reference Item list specifying options for the routine. This routine does not use the in_item_list argument. 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. This routine does not use the out_item_list argument. 3 Description The MAIL$SEND_END routine deallocates the send context as well as any dynamic memory allocated by previous send routine calls. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. Any condition value returned by LIB$FREE_VM. 2 MAIL$SEND_MESSAGE Begins the actual sending of the message after the message has been constructed. Format MAIL$SEND_MESSAGE context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Send context information to be passed to send routines. The context argument is the address of a longword that contains send context information returned by MAIL$SEND_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$_SEND_ERROR_ENTRY MAIL$_SEND_ERROR_ENTRY specifies the longword address of an entry point to process errors during a send operation. The descriptor of the recipient that failed, the address of the signal array, and the user-specified data are passed as input to the routine. Refer to the HP OpenVMS Programming Concepts Manual for more information about the signal array and its use by condition- handling routines. MAIL$_SEND_RECIP_FOLDER MAIL$_SEND_RECIP_FOLDER specifies the descriptor of a recipients folder name. If you do not specify the MAIL$_SEND_RECIP_FOLDER item code, the mail will be sent to the default NEWMAIL folder. A valid folder name can be 1 to 39 characters in length. MAIL$_SEND_SUCCESS_ENTRY MAIL$_SEND_SUCCESS_ENTRY specifies the longword address of an entry point to process successes during a send operation. The descriptor of the recipient that succeeded, the address of the signal array, and the user-specified data are passed as input to the routine. Refer to the HP OpenVMS Programming Concepts Manual for more information about the signal array and its use by condition-handling routines. MAIL$_SEND_USER_DATA MAIL$_SEND_USER_DATA specifies a longword that MAIL$SEND_MESSAGE passes to the SEND action routines. 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. 3 Output_Item_Codes None. 3 Description The MAIL$SEND_MESSAGE routine sends a message built with the MAIL$SEND_ADD_BODYPART routine to every user on the address list. If you have not used MAIL$SEND_ADD_BODYPART to construct a message, MAIL$SEND_MESSAGE sends only a message header. If MAIL$SEND_MESSAGE encounters errors sending to an addressee, it calls the routine specified by MAIL$_SEND_ERROR_ENTRY. Otherwise, it calls the routine specified by MAIL$_SEND_SUCCESS_ ENTRY. If either routine is not specified, MAIL$SEND_MESSAGE calls no other routines. If you specify the MAIL$_SEND_RECIP_FOLDER item code, the mail is placed in the specified folder. Otherwise, the mail is sent to the default NEWMAIL folder. 3 Condition_Values_Returned MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. Any condition value returned by $CONNECT. 2 MAIL$USER_BEGIN Initiates access to the Mail common user database. You must call MAIL$USER_BEGIN before you call any other user routines. Format MAIL$USER_BEGIN context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context information to be passed to other user routines. The context argument is the address of a longword that contains user context information. You should specify the value of this argument as 0 in the first of a sequence of calls to MAIL routines. In following calls, you should specify the user 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. This routine does not use the in_item_list argument. 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. 3 Output_Item_Codes MAIL$_USER_AUTO_PURGE When you specify the Boolean item code MAIL$_USER_AUTO_PURGE, MAIL$USER_BEGIN returns the value of the automatic purge mail flag as a longword value. MAIL$_USER_CAPTIVE When you specify the Boolean item code MAIL$_USER_CAPTIVE, MAIL$USER_BEGIN returns the value of the UAF CAPTIVE flag as a longword value. MAIL$_USER_CC_PROMPT When you specify the Boolean item code MAIL$_USER_CC_PROMPT, MAIL$USER_BEGIN returns the value of the cc prompt flag as a longword value. MAIL$_USER_COPY_FORWARD When you specify the Boolean item code MAIL$_USER_COPY_FORWARD, MAIL$USER_BEGIN returns the value of the copy self forward flag as a longword value. MAIL$_USER_COPY_REPLY When you specify the Boolean item code MAIL$_USER_COPY_REPLY, MAIL$USER_BEGIN returns the value of the copy self reply flag as a longword value. MAIL$_USER_COPY_SEND When you specify the Boolean item code MAIL$_USER_COPY_SEND, MAIL$USER_BEGIN returns the value of the copy self send flag as a longword value. MAIL$_USER_FORWARDING When you specify MAIL$_USER_FORWARDING, MAIL$USER_BEGIN returns the forwarding address string. 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$_USER_FORM When you specify MAIL$_USER_FORM, MAIL$USER_BEGIN returns the default print form string. 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$_USER_FULL_DIRECTORY When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_BEGIN returns complete directory path of the MAIL subdirectory. 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$_USER_NEW_MESSAGES When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_BEGIN returns the new message count. The buffer address field of the item descriptor points to a word that receives the new message count. MAIL$_USER_PERSONAL_NAME When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_BEGIN returns the personal name string. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 127 characters long. Specify a value from 0 to 127 in the buffer length field of the item descriptor. MAIL$_USER_QUEUE When you specify MAIL$_USER_QUEUE, MAIL$USER_BEGIN returns the default print queue name. 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$_USER_RETURN_USERNAME When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_BEGIN returns the user name string. 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$_USER_SIGFILE When you specify MAIL$_USER_SIGFILE, MAIL$USER_BEGIN returns the default signature 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$_USER_SUB_DIRECTORY When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_BEGIN returns the subdirectory 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. 3 Description MAIL$USER_BEGIN creates and initializes a user database context for subsequent calls to other user routines. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. 2 MAIL$USER_DELETE_INFO Removes a record from the user profile database. Format MAIL$USER_DELETE_INFO context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context information to be passed to send routines. The context argument is the address of a longword that contains user context information returned by MAIL$USER_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 must include at least one device item descriptor. The item list is terminated by longword value of 0. 3 Input_Item_Codes MAIL$_USER_USERNAME MAIL$_USER_USERNAME specifies the record to be deleted from the user profile database. The buffer address field of the item descriptor points to a buffer that contains the user name string encoded in a character string 0 to 31 characters long. Specify a value from 0 to 31 in the buffer length field of the item descriptor. Setting bit 4 of DCL_CTLFLAGS, enables the user name string encoded in a character string 0 to 255 characters long. NOTE Once this bit is set, user name length is set to a maximum of 255 characters long. Even if this bit is cleared, the behavior remains unchanged, that is, supports user name length of 255 characters long, but there is no way to reset it to 31 characters long. The item code MAIL$_USER_USERNAME is required. 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. 3 Output_Item_Codes None. 3 Description To delete a record from the user profile database, you must have SYSPRV privilege. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. MAIL$_NOSUCHUSR The specified user name is not valid. MAIL$_NOSYSPRV The operation requires the SYSPRV privilege. SS$_ACCVIO Access violation. 2 MAIL$USER_END Terminates access to the user profile database. Format MAIL$USER_END context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context information to be passed to user routines. The context argument is the address of a longword that contains user context information. If the Mail utility terminates access to the user profile database successfully, the value of the argument context is changed to 0. in_item_list OpenVMS usage:itmlst_3 type: longword (unsigned) access: read only mechanism: by reference Item list specifying options for the routine. This routine does not use the in_item_list argument. 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. This routine does not use the out_item_list argument. 3 Description The MAIL$USER_END routine deallocates the user database context created by MAIL$USER_BEGIN as well as all dynamic memory allocated by previous user routines. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. SS$_ACCVIO Access violation. Any condition value returned by LIB$FREE_VM. 2 MAIL$USER_GET_INFO Obtains information about a user from the user profile database. Format MAIL$USER_GET_INFO context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context information to be passed to user routines. The context argument is the address of a longword that contains user context information returned by MAIL$USER_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 must include at least one device item descriptor. The item list is terminated by longword value of 0. 3 Input_Item_Codes MAIL$_USER_FIRST The Boolean item code MAIL$_USER_FIRST specifies that MAIL$USER_ GET_INFO return information in the user profile about the first entry in the user profile database. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_USER_ USERNAME in the same call to MAIL$USER_GET_INFO. MAIL$_USER_NEXT The Boolean item code MAIL$_USER_NEXT specifies that MAIL$USER_ GET_INFO return information in the user profile about the next user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_USER_ USERNAME in the same call to MAIL$USER_GET_INFO. MAIL$_USER_USERNAME The item code MAIL$_USER_USERNAME points to the username string. Specify the address of the username string in the buffer address field and specify the length of the username string in the buffer length field of the item descriptor. Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT and MAIL$_USER_ USERNAME in the same call to MAIL$USER_GET_INFO. 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. 3 Output_Item_Codes MAIL$_USER_AUTO_PURGE When you specify the Boolean item code MAIL$_USER_AUTO_PURGE, MAIL$USER_GET_INFO returns the value of the automatic purge mail flag as a longword value. MAIL$_USER_CC_PROMPT When you specify the Boolean item code MAIL$_USER_CC_PROMPT, MAIL$USER_GET_INFO returns the value of the cc prompt flag as a longword value. MAIL$_USER_COPY_FORWARD When you specify the Boolean item code MAIL$_USER_COPY_FORWARD, MAIL$USER_GET_INFO returns the value of the copy self forward mail flag as a longword value. MAIL$_USER_COPY_REPLY When you specify the Boolean item code MAIL$_USER_COPY_REPLY, MAIL$USER_GET_INFO returns the value of the copy self reply mail flag as a longword value. MAIL$_USER_COPY_SEND When you specify the Boolean item code MAIL$_USER_COPY_SEND, MAIL$USER_GET_INFO returns the value of the copy self send mail flag as a longword value. MAIL$_USER_EDITOR When you specify MAIL$_USER_EDITOR, MAIL$USER_GET_INFO returns the name of the default editor. 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$_USER_FORWARDING When you specify MAIL$_USER_FORWARDING, MAIL$USER_GET_INFO returns the forwarding address. 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$_USER_FORM When you specify MAIL$_USER_FORM, MAIL$USER_GET_INFO returns the default print form string. 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$_USER_FULL_DIRECTORY When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_GET_INFO returns the complete directory path of the MAIL subdirectory string. 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$_USER_NEW_MESSAGES When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_GET_INFO returns the new messages count. The buffer address field of the item descriptor points to a word that receives the new message count as a word value. MAIL$_USER_PERSONAL_NAME When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_GET_INFO returns the personal name string. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 127 characters long. Specify a value from 0 to 127 in the buffer length field of the item descriptor. MAIL$_USER_QUEUE When you specify MAIL$_USER_QUEUE, MAIL$USER_GET_INFO returns the default print queue name string. 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$_USER_RETURN_USERNAME When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_GET_INFO returns the user name. 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$_USER_SIGFILE When you specify MAIL$_USER_SIGFILE, MAIL$USER_GET_INFO returns the default signature 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$_USER_SUB_DIRECTORY When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_GET_INFO returns the MAIL subdirectory specification string. 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. 3 Description The MAIL$USER_GET_INFO routine returns information about specified entries in the user profile database. If you do not specify a user name, MAIL$USER_GET_INFO returns information about the user name associated with the calling process. To obtain information about a user name other than that associated with the calling process, you need the SYSNAM privilege. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_CONITMCOD The specified item codes perform conflicting operations. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. MAIL$_NOSUCHUSR The specified user name is invalid. MAIL$_NOSYSPRV The specified operation requires the SYSPRV privilege. SS$_ACCVIO Access violation. 2 MAIL$USER_SET_INFO Adds or modifies a specified user record in the user profile database. Format MAIL$USER_SET_INFO context ,in_item_list ,out_item_list 3 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. 3 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context information to be passed to user routines. The context argument is the address of a longword that contains user context information returned by MAIL$USER_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 must include at least one device item descriptor. The item list is terminated by longword value of 0. 3 Input_Item_Codes MAIL$_USER_CREATE_IF The Boolean item code MAIL$_USER_CREATE_IF specifies that MAIL$USER_SET_INFO should create the record for the specified user if it does not already exist. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_AUTO_PURGE The Boolean item codes MAIL$_USER_SET_AUTO_PURGE and MAIL$_ USER_SET_NO_AUTO_PURGE set and clear the auto purge flag for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_CC_PROMPT The Boolean item codes MAIL$_USER_SET_CC_PROMPT and MAIL$_ USER_SET_NO_CC_PROMPT set and clear the cc prompt flag for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_COPY_FORWARD The Boolean item codes MAIL$_USER_SET_COPY_FORWARD and MAIL$_ USER_SET_NO_COPY_FORWARD set and clear the copy self forward flag for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_COPY_REPLY The Boolean item codes MAIL$_USER_SET_COPY_REPLY and MAIL$_USER_ SET_NO_COPY_REPLY set and clear the copy self reply flag for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_COPY_SEND The Boolean item codes MAIL$_USER_SET_COPY_SEND and MAIL$_USER_ SET_NO_COPY_SEND set and clear the copy self send flag for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_EDITOR MAIL$_USER_SET_EDITOR specifies the name of a default editor to be used by the specified user. 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 Boolean item code MAIL$_USER_SET_NO_EDITOR clears the default editor field for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_FORM MAIL$_USER_SET_FORM specifies the default print form string for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_FORM clears the default print form field for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_FORWARDING MAIL$_USER_SET_FORWARDING specifies a forwarding address string for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_FORWARDING clears the forwarding address field for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_NEW_MESSAGES MAIL$_USER_SET_NEW_MESSAGES specifies the new message count for the specified user. The buffer address field of the item descriptor points to a word that contains the new number of new messages. MAIL$_USER_SET_PERSONAL_NAME MAIL$_USER_SET_PERSONAL_NAME specifies a personal name string for the specified user. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 127 characters long. Specify a value from 0 to 127 in the buffer length field of the item descriptor. The Boolean item code MAIL$_USER_SET_NO_PERSONAL_NAME clears the personal field for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_QUEUE MAIL$_USER_SET_QUEUE specifies a default print queue name string for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_QUEUE clears the default print queue field for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_SIGFILE MAIL$_USER_SET_SIGFILE specifies a signature file specification for the specified user. 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 Boolean item code MAIL$_USER_SET_NO_SIGFILE clears the signature file field for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_SET_SUB_DIRECTORY MAIL$_USER_SET_SUB_DIRECTORY specifies a MAIL subdirectory. 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 Boolean item code MAIL$_USER_SET_NO_SUB_DIRECTORY disables the use of a MAIL subdirectory for the specified user. Specify the value 0 in the buffer length and buffer address fields of the item descriptor. MAIL$_USER_USERNAME MAIL$_USER_USERNAME specifies the record to be modified in the user profile database and points to the user name string. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 31 characters long. Specify a value from 0 to 31 in the buffer length field of the item descriptor. Setting bit 4 of DCL_CTLFLAGS, enables the user name string encoded in a character string 0 to 255 characters long. NOTE Once this bit is set, user name length is set to a maximum of 255 characters long. Even if this bit is cleared, the behavior remains unchanged, that is, supports user name length of 255 characters long, but there is no way to reset it to 31 characters long. 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. 3 Output_Item_Codes None. 3 Description The MAIL$USER_SET_INFO routine modifies specified records in the user profile database. If you do not specify a user name, the routine modifies the user record associated with the calling process. To modify any user record other than that associated with the calling process, you must have SYSPRV privilege. However, if you want to add or modify only the forwarding address of another user, SYSNAM privilege is sufficient. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. MAIL$_CONITMCOD The specified item codes perform conflicting operations. MAIL$_ILLCHAR Unacceptable character in personal name. Utility returns three formatted ASCII output (FAO) arguments including the illegal character, the length of the string, and the string address. MAIL$_ILLPERNAM Personal name formatted improperly. Returns an FAO argument containing the improperly formatted personal name. MAIL$_ILLSUBDIR Illegal subdirectory specification. Returns an FAO argument containing the subdirectory string. MAIL$_INVITMCOD The specified item code is invalid. MAIL$_INVITMLEN The specified item length is invalid. MAIL$_MISREQITEM The required item is missing. MAIL$_NAMTOOBIG Specified name exceeds 255-character limit. MAIL$_NOTSUBDIR No such subdirectory. Returns an FAO argument containing the subdirectory string. MAIL$_NOSUCHUSR No such user. Returns the name of the unfound user. MAIL$_NOSYSNAM Caller needs SYSNAM privileges. MAIL$_NOSYSPRV Caller needs system privileges. SS$_ACCVIO Access violation.