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

    The SMB$READ_MESSAGE routine copies a message that the job
    controller has sent into the caller's specified buffer.

    Format

      SMB$READ_MESSAGE  stream ,buffer ,request

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:       write only
    mechanism:    by reference
    Stream number specifying the stream to which the message refers.
    The stream argument is the address of a longword into which the
    job controller writes the number of the stream referred to by
    the message. In single-threaded symbionts, the stream number is
    always 0.

 buffer

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor
    Address of the descriptor that points to the buffer into which
    the job controller writes the message. SMB$READ_MESSAGE uses
    the Run-Time Library string-handling (STR$) routines to copy
    the message into the buffer you supply. The buffer should be
    specified by a dynamic string descriptor.

 request

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Code that identifies the request. The request argument is the
    address of a longword into which SMB$READ_MESSAGE writes the code
    that identifies the request.

    There are seven request codes. Each code is interpreted as a
    message by the symbiont. The codes and their descriptions follow:

    SMBMSG$K_START_       Initiates processing on an inactive
    STREAM                symbiont stream. The job controller sends
                          this message when a START/QUEUE or an
                          INITIALIZE/QUEUE/START command is issued
                          on a stopped queue.
    SMBMSG$K_STOP_        Stops processing on a started queue. The
    STREAM                job controller sends this message when a
                          STOP/QUEUE/NEXT command is issued, after
                          the symbiont completes any currently active
                          task.
    SMBMSG$K_RESET_       Aborts all processing on a started stream
    STREAM                and requeues the current job. The job
                          controller sends this message when a
                          STOP/QUEUE/RESET command is issued.
    SMBMSG$K_START_TASK   Requests that the symbiont begin processing
                          a task. The job controller sends this
                          message when a file is pending on an idle,
                          started queue.
    SMBMSG$K_STOP_TASK    Requests that the symbiont abort the
                          processing of a task. The job controller
                          sends this message when a STOP/QUEUE/ABORT
                          or STOP/QUEUE/REQUEUE command is issued.
                          The item SMBMSG$K_STOP_CONDITION identifies
                          whether this is an abort or a requeue
                          request.
    SMBMSG$K_PAUSE_TASK   Requests that the symbiont pause in the
                          processing of a task but retain the
                          resources necessary to continue. The
                          job controller sends this message when
                          a STOP/QUEUE command is issued without
                          the /ABORT, /ENTRY, /REQUEUE, or /NEXT
                          qualifier for a queue that is currently
                          printing a job.
    SMBMSG$K_RESUME_      Requests that the symbiont continue
    TASK                  processing a task that has been stopped
                          with a PAUSE_TASK request. This message is
                          sent when a START/QUEUE command is issued
                          for a queue served by a symbiont that has
                          paused in processing the current task.

3 - Description

    Your symbiont calls SMB$READ_MESSAGE to read a message that the
    job controller has sent to the symbiont.

    Each message from the job controller consists of a code
    identifying the function the symbiont is to perform and a number
    of message items. There are seven codes. Message items are pieces
    of information that the symbiont needs to carry out the requested
    function.

    For example, when you enter the DCL command PRINT, the job
    controller sends a message containing a START_TASK code and
    a message item containing the specification of the file to be
    printed.

    SMB$READ_MESSAGE writes the code into a longword (specified by
    the request argument) and writes the accompanying message items,
    if any, into a buffer (specified by the buffer argument).

    See the description of the SMB$READ_MESSAGE_ITEM routine for
    information about processing the individual message items.

4 - Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    LIB$_INVARG        Routine completed unsuccessfully because of an
                       invalid argument.

    This routine also returns any of the condition codes returned by
    the Run-Time Library string-handling (STR$) routines.