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

    The SMB$SEND_TO_JOBCTL routine is used by your symbiont to send
    messages to the job controller. Three types of messages can be
    sent: request-completion messages, task-completion messages, and
    task-status messages.

    Format

      SMB$SEND_TO_JOBCTL  stream [,request] [,accounting]

                          [,checkpoint] [,device_status] [,error]

1 - Returns

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

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

2 - Arguments

 stream

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Stream number specifying the stream to which the message refers.
    The stream argument is the address of a longword containing the
    number of the stream to which the message refers.

 request

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Request code identifying the request being completed. The request
    argument is the address of a longword containing the code that
    identifies the request that has been completed.

    The code usually corresponds to the code the job controller
    passed to the symbiont by means of a call to SMB$READ_MESSAGE.
    But the symbiont can also initiate task-completion and task-
    status messages that are not in response to a request. (See the
    Description section.)

 accounting

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Accounting information about a task. The accounting argument
    is the address of a descriptor pointing to the accounting
    information about a task. Note that this structure is passed
    by descriptor and not by reference.

    The job controller accumulates task statistics into a job-
    accounting record, which it writes to the accounting file when
    the job is completed.

    The following diagram depicts the contents of the 16-byte
    structure:

 checkpoint

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Checkpoint data about the currently executing task. The
    checkpoint argument is the address of the descriptor that points
    to checkpointing information that relates to the status of
    a task. When the symbiont sends this information to the job
    controller, the job controller saves it in the queue database.
    When a restart-from-checkpoint request is executed for the queue,
    the job controller retrieves the checkpointing information from
    the queue database and sends it to the symbiont in the SMBMSG$K_
    CHECKPOINT_DATA item that accompanies a SMBMSG$K_START_TASK
    request.

    Print symbionts can use the checkpointing information to
    reposition the input file to the point corresponding to the page
    being output when the last checkpoint was taken. Other symbionts
    might use checkpoint information to specify restart information
    for partially completed tasks.

                                   NOTE

       Because each checkpoint causes information to be written
       into the job controller's queue database, taking a
       checkpoint incurs significant overhead. Use caution in
       regard to the size and frequency of checkpoints. When
       determining how often to checkpoint, weigh processor and
       file-system overhead against the convenience of restarting.

 device_status

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Status of the device served by the symbiont. The device_
    status argument is the address of a longword passed to the job
    controller, which contains the status of the device to which the
    symbiont is connected.

    This longword contains a longword bit vector, each bit of which
    specifies device-status information. Each programming language
    provides an appropriate mechanism for defining these device-
    status bits. The following table describes each bit:

    Device Status Bit    Description

    SMBMSG$V_LOWERCASE   The device to which the symbiont is
                         connected supports lowercase characters.
    SMBMSG$V_PAUSE_      The symbiont sends this message to inform
    TASK                 the job controller that the symbiont has
                         paused on its own initiative.
    SMBMSG$V_REMOTE      The device is connected to the symbiont by
                         means of a modem.
    SMBMSG$V_SERVER      The symbiont is not connected to a device.
    SMBMSG$V_STALLED     Symbiont processing is temporarily stalled.
    SMBMSG$V_STOP_       The symbiont requests that the job
    STREAM               controller stop the queue.
    SMBMSG$V_TERMINAL    The symbiont is connected to a terminal.
    SMBMSG$V_            The device to which the symbiont is
    UNAVAILABLE          connected is not available.

 error

    OpenVMS usage:vector_longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Condition codes returned by the requested task. The error
    argument is the address of a vector of longword condition codes.
    The first longword contains the number of longwords following it.

    If the low bit of the first condition code is clear, the job
    controller aborts further processing of the job. Output of
    any remaining files, copies of files, or copies of the job is
    canceled. In addition, the job controller saves up to three
    condition values in the queue database. The first condition value
    is included in the job-accounting record that is written to the
    system's accounting file (SYS$MANAGER:ACCOUNTNG.DAT).

3 - Description

    The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages
    to the job controller.

    Most messages the symbiont sends to the job controller are
    responses to requests made by the job controller. These responses
    inform the job controller that the request has been completed,
    either successfully or with an error. When the symbiont sends
    the message, it usually indicates that the request has been
    completed.

    In such messages, the request argument corresponds to the
    function code of the request that has been completed. Thus, if
    the job controller sends a request using the SMBMSG$K_START_
    TASK code, the symbiont responds by sending a SMB$SEND_TO_JOBCTL
    message using SMBMSG$K_START_TASK as the request argument.

    The responses to some requests use additional arguments to send
    more information in addition to the request code. The following
    table shows which additional arguments are allowed in response to
    each different request:

    Request                Arguments

    SMBMSG$K_START_STREAM  request
                           device_status
                           error
    SMBMSG$K_STOP_STREAM   request
    SMBMSG$K_RESET_STREAM  request
    SMBMSG$K_START_TASK    request
    SMBMSG$K_PAUSE_TASK    request
    SMBMSG$K_RESUME_TASK   request
    SMBMSG$K_STOP_TASK     request
                           error

    In addition to responding to requests from the job controller,
    the symbiont can send other messages to the job controller. If
    the symbiont sends a message that is not a response to a request,
    it uses either the SMBMSG$K_TASK_COMPLETE or SMBMSG$K_TASK_STATUS
    code. Following are the additional arguments that you can use
    with the messages identified by these codes:

    Code                   Arguments

    SMBMSG$K_TASK_         request
    COMPLETE
                           accounting
                           error
    SMBMSG$K_TASK_STATUS   request
                           checkpoint
                           device_status

    The symbiont uses the SMBMSG$K_TASK_STATUS message to update the
    job controller on the status of a task during the processing
    of that task. The checkpoint information passed to the job
    controller with this message permits the job controller to
    restart an interrupted task from an appropriate point. The
    device-status information permits the symbiont to report changes
    in device's status (device stalled, for example).

    The symbiont can use the SMBMSG$K_TASK_STATUS message to request
    that the job controller send a stop-stream request. It does this
    by setting the stop-stream bit in the device-status argument.

    The symbiont can also use the SMBMSG$K_TASK_STATUS message
    to notify the job controller that the symbiont has paused in
    processing a task. It does so by setting the pause-task bit in
    the device-status argument.

    The symbiont uses the SMBMSG$K_TASK_COMPLETE message to signal
    the completion of a task. Note that, when the symbiont receives a
    START_TASK request, it responds by sending a SMB$SEND_TO_JOBCTL
    message with SMBSMG$K_START_TASK as the request argument. This
    response means that the symbiont has started the task; it does
    not mean the task has been completed. When the symbiont has
    completed a task, it sends a SMB$SEND_TO_JOBCTL message with
    SMBMSG$K_TASK_COMPLETE as the request argument.

    Optionally, the symbiont can specify accounting information when
    sending a task-completion message. The accounting statistics
    accumulate to give a total for the job when the job is completed.

    Also, if the symbiont is aborting the task because of a symbiont-
    detected error, you can specify up to three condition values in
    the error argument. Aborting a task causes the remainder of the
    job to be aborted.

4 - Condition Values Returned

    SS$_NORMAL         Normal successful completion.

    This routine also returns any condition value returned by the
    $QIO system service and the LIB$GET_VM routine.