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.