VMS Help  —  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.

1  –  MAIL$MAILFILE_BEGIN

    Initiates mail file processing.

    Format

      MAIL$MAILFILE_BEGIN  context ,in_item_list ,out_item_list

1.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

1.2  –  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.

1.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

2.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

2.2  –  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.

2.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 VSI.

 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.

2.4  –  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.

2.5  –  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.

2.6  –  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.

3  –  MAIL$MAILFILE_COMPRESS

    Compresses a mail file.

    Format

      MAIL$MAILFILE_COMPRESS  context ,in_item_list ,out_item_list

3.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

3.2  –  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.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.4  –  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.5  –  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.6  –  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.

4  –  MAIL$MAILFILE_END

    Terminates mail file processing.

    Format

      MAIL$MAILFILE_END  context ,in_item_list ,out_item_list

4.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

4.2  –  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.

4.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.

4.4  –  Output Item Codes

    None.

4.5  –  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.

4.6  –  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.

5  –  MAIL$MAILFILE_INFO_FILE

    Obtains information about a specified mail file.

    Format

      MAIL$MAILFILE_INFO_FILE  context ,in_item_list ,out_item_list

5.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

5.2  –  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.

5.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.

5.4  –  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.

5.5  –  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.

5.6  –  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.

6  –  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

6.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

6.2  –  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.

6.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.

6.4  –  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.

6.5  –  Description

    If a mail file is not specified, the currently open mail file is
    used.

6.6  –  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.

7  –  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

7.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

7.2  –  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.

7.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.

7.4  –  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.

7.5  –  Description

    The default mail file specification is MAIL.MAI in the MAIL
    subdirectory.

7.6  –  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.

8  –  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

8.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

8.2  –  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.

8.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.

8.4  –  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.

8.5  –  Description

    If you specify the MAIL$_MAILFILE_RECLAIM item descriptor,
    all the bytes deleted from the mail file by this routine are
    reclaimed.

8.6  –  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.

9  –  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

9.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

9.2  –  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.

9.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.

9.4  –  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.

9.5  –  Description

    MAIL$MESSAGE_BEGIN creates and initializes a message context for
    subsequent calls to message routines.

9.6  –  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.

10  –  MAIL$MESSAGE_COPY

    Copies messages between files or folders.

    Format

      MAIL$MESSAGE_COPY  context ,in_item_list ,out_item_list

10.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

10.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information returned by MAIL$MESSAGE_BEGIN.

    You should specify this argument as 0 in the first of a sequence
    of calls to message routines. In the following calls, you should
    specify the message context value returned by the previous
    routine.

 in_item_list

    OpenVMS usage:itmlst_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying options for the routine. The in_item_list
    argument is the address of a list of item descriptors, each of
    which specifies an option and provides the information needed to
    perform the operation.

    The item list is terminated by longword value of 0.

10.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.

10.4  –  Output Item Codes

 MAIL$_MESSAGE_FILE_CREATED

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

 MAIL$_MESSAGE_FOLDER_CREATED

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

 MAIL$_MESSAGE_RESULTSPEC

    When you specify MAIL$_MESSAGE_RESULTSPEC, MAIL$MESSAGE_COPY
    returns the mail file resultant file specification. The buffer
    address field of the item descriptor points to a buffer that
    receives a character string 0 to 255 characters long.

    Specify a value from 0 to 255 in the buffer length field of the
    item descriptor.

10.5  –  Description

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

10.6  –  Condition Values Returned

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

11  –  MAIL$MESSAGE_DELETE

    Deletes a specified message from the currently selected folder.

    Format

      MAIL$MESSAGE_DELETE  context ,in_item_list ,out_item_list

11.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

11.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information.

 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.

11.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.

11.4  –  Output Item Codes

    None.

11.5  –  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.

11.6  –  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.

12  –  MAIL$MESSAGE_END

    Ends message processing.

    Format

      MAIL$MESSAGE_END  context ,in_item_list ,out_item_list

12.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

12.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information returned by MAIL$MESSAGE_BEGIN. 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.

12.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.

12.4  –  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.

13  –  MAIL$MESSAGE_GET

    Retrieves a message from the set of currently selected messages.

    Format

      MAIL$MESSAGE_GET  context ,in_item_list ,out_item_list

13.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

13.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information returned by MAIL$MESSAGE_BEGIN.

 in_item_list

    OpenVMS usage:itmlst_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying options for the routine. The in_item_list
    argument is the address of a list of item descriptors, each of
    which specifies an option and provides the information needed to
    perform the operation.

    The item list is terminated by longword value of 0.

13.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.

13.4  –  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.

13.5  –  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.

13.6  –  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.

14  –  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

14.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

14.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information returned by MAIL$MESSAGE_BEGIN.

 in_item_list

    OpenVMS usage:itmlst_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying options for the routine. The in_item_list
    argument is the address of a list of item descriptors, each of
    which specifies an option and provides the information needed to
    perform the operation.

    The item list is terminated by longword value of 0.

14.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.

14.4  –  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.

14.5  –  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.

14.6  –  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.

15  –  MAIL$MESSAGE_MODIFY

    Modifies information in the message header.

    Format

      MAIL$MESSAGE_MODIFY  context ,in_item_list ,out_item_list

15.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

15.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information returned by MAIL$MESSAGE_BEGIN.

 in_item_list

    OpenVMS usage:itmlst_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying options for the routine. The in_item_list
    argument is the address of a list of item descriptors, each of
    which specifies an option and provides the information needed to
    perform the operation.

    The item list is terminated by longword value of 0.

15.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.

15.4  –  Output Item Code

 MAIL$_MESSAGE_CURRENT_ID

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

15.5  –  Condition Values Returned

    MAIL$_CONITMCOD    The specified item codes define conflicting
                       operations.
    MAIL$_DELMSG       The message is deleted.
    MAIL$_ILLCTXADR    The context block address is illegal.
    MAIL$_INVITMCOD    The specified item code is invalid.
    MAIL$_INVITMLEN    The specified item length is invalid.
    MAIL$_MISREQITEM   The required item is missing.
    MAIL$_NOFILEOPEN   The mail file is not open.
    MAIL$_NOMOREMSG    No more messages.
    MAIL$_WRONGCTX     The context block is incorrect.
    MAIL$_WRONGFILE    The specified file is incorrect in this
                       context.
    SS$_ACCVIO         Access violation.
    Any condition value returned by $FIND and $UPDATE.

16  –  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

16.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

16.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Message context information to be passed to message routines.
    The context argument is the address of a longword that contains
    message context information returned by MAIL$MESSAGE_BEGIN.

 in_item_list

    OpenVMS usage:itmlst_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying options for the routine. The in_item_list
    argument is the address of a list of item descriptors, each of
    which specifies an option and provides the information needed to
    perform the operation.

    The item list is terminated by longword value of 0.

16.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.

16.4  –  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.

16.5  –  Description

    MAIL$MESSAGE_SELECT deselects previously selected messages
    whether or not you request a valid selection.

16.6  –  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.

17  –  MAIL$SEND_ABORT

    Cancels a currently executing send operation.

    Format

      MAIL$SEND_ABORT  context ,in_item_list ,out_item_list

17.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Value Returned.

17.2  –  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.

17.3  –  Description

    MAIL$SEND_ABORT is useful when, for example, the user presses
    Ctrl/C during the execution of MAIL$SEND_MESSSAGE.

17.4  –  Condition Value Returned

    SS$_NORMAL         Normal successful completion.

18  –  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

18.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

18.2  –  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.

18.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.

18.4  –  Output Item Codes

    None.

18.5  –  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.

18.6  –  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.

19  –  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

19.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

19.2  –  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.

19.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.

19.4  –  Output Item Codes

    None.

19.5  –  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).

19.6  –  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.

20  –  MAIL$SEND_ADD_BODYPART

    Builds the body of a message.

    Format

      MAIL$SEND_ADD_BODYPART  context ,in_item_list ,out_item_list

20.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

20.2  –  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.

20.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.

20.4  –  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.

20.5  –  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.

20.6  –  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.

21  –  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

21.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

21.2  –  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.

21.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.

21.4  –  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.

21.5  –  Description

    MAIL$SEND_BEGIN creates and initializes a send context for
    subsequent calls to send routines.

21.6  –  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.

22  –  MAIL$SEND_END

    Terminates send processing.

    Format

      MAIL$SEND_END  context ,in_item_list ,out_item_list

22.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

22.2  –  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.

22.3  –  Description

    The MAIL$SEND_END routine deallocates the send context as well as
    any dynamic memory allocated by previous send routine calls.

22.4  –  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.

23  –  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

23.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

23.2  –  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.

23.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 VSI 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 recipient's
    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 VSI 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.

23.4  –  Output Item Codes

    None.

23.5  –  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.

23.6  –  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.

24  –  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

24.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

24.2  –  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.

24.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.

24.4  –  Description

    MAIL$USER_BEGIN creates and initializes a user database context
    for subsequent calls to other user routines.

24.5  –  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.

25  –  MAIL$USER_DELETE_INFO

    Removes a record from the user profile database.

    Format

      MAIL$USER_DELETE_INFO  context ,in_item_list ,out_item_list

25.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

25.2  –  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.

25.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.

25.4  –  Output Item Codes

    None.

25.5  –  Description

    To delete a record from the user profile database, you must have
    SYSPRV privilege.

25.6  –  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.

26  –  MAIL$USER_END

    Terminates access to the user profile database.

    Format

      MAIL$USER_END  context ,in_item_list ,out_item_list

26.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

26.2  –  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.

26.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.

26.4  –  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.

27  –  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

27.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

27.2  –  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.

27.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.

27.4  –  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.

27.5  –  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.

27.6  –  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.

28  –  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

28.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. All utility routines return a condition
    value in R0. Condition values that can be returned by this
    routine are listed under Condition Values Returned.

28.2  –  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.

28.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.

28.4  –  Output Item Codes

    None.

28.5  –  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.

28.6  –  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.
Close Help