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

    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

1 - Returns

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

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

2 - Arguments

 context

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

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

 in_item_list

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

    The item list is terminated by longword value of 0.

3 - Input Item Codes

 MAIL$_SEND_PERS_NAME   MAIL$_SEND_NO_PERS_NAME

    Note that you must specify only one of these item codes. An error
    is generated if you specify both item codes. MAIL$_SEND_PERS_
    NAME specifies the personal name text to be used in the message
    header. The buffer address field of the item descriptor points
    to a buffer that contains a character string 0 to 127 characters
    long.

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

    The Boolean item code MAIL$_SEND_NO_PERS_NAME specifies that no
    personal name string be used during message construction.

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

 MAIL$_SEND_SIGFILE   MAIL$_SEND_NO_SIGFILE

    Note that you must specify only one of these item codes. An
    error is generated if you specify both item codes. MAIL$_
    SEND_SIGFILE specifies the full OpenVMS file specification
    of the signature file to be used in the message. The default
    file specification used for a signature file is the user mail
    directory specification and .SIG as the file type. The buffer
    address field of the item descriptor points to a buffer that
    contains a character string 0 to 255 characters long.

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

    The Boolean item code MAIL$_SEND_NO_SIGFILE specifies that no
    signature file be used during message construction.

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

 out_item_list

    OpenVMS usage:itmlst_3
    type:         longword
    access:       write only
    mechanism:    by reference
    Item list specifying the information you want the routine to
    return. The out_item_list argument is the address of a list of
    item descriptors, each of which describes an item of information.
    The list of item descriptors is terminated by longword value of
    0.

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.

5 - Description

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

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.