1  SMB_Routines
   The Symbiont/Job Controller Interface (SMB) routines provide the
   interface between the job controller and symbiont processes. A
   user-written symbiont must use these routines to communicate with
   the job controller.
 

2  SMB$CHECK_FOR_MESSAGE
   The SMB$CHECK_FOR_MESSAGE routine determines whether a message
   sent from the job controller to the symbiont is waiting to be
   read.

   Format

     SMB$CHECK_FOR_MESSAGE
 

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

3  Arguments
   None.
 

3  Description
   When your symbiont calls the SMB$INITIALIZE routine to initialize
   the interface between the symbiont and the job controller, you
   can choose to have requests from the job controller delivered
   by means of an AST. If you choose not to use ASTs, your symbiont
   must call SMB$CHECK_FOR_MESSAGE during the processing of tasks in
   order to see if a message from the job controller is waiting to
   be read. If a message is waiting, SMB$CHECK_FOR_MESSAGE returns a
   success code; if not, it returns a zero.

   If a message is waiting, the symbiont should call SMB$READ_
   MESSAGE to read it to determine if immediate action should be
   taken (as in the case of STOP_TASK, RESET_STREAM or PAUSE_TASK).

   If a message is not waiting, SMB$CHECK_MESSAGE returns a zero.
   If this condition is detected, the symbiont should continue
   processing the request at hand.
 

3  Condition_Values_Returned

   SS$_NORMAL         One or more messages waiting.
   0                  No messages waiting.
 

2  SMB$INITIALIZE
   The SMB$INITIALIZE routine initializes the user-written symbiont
   and the interface between the symbiont and the job controller. It
   allocates and initializes the internal databases of the interface
   and sets up the mechanism that is to wake up the symbiont when a
   message is received.

   Format

     SMB$INITIALIZE  structure_level [,ast_routine] [,streams]
 

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

3  Arguments
 

structure_level

   OpenVMS usage:longword_unsigned
   type:         longword (unsigned)
   access:       read only
   mechanism:    by reference
   Version of the symbiont/job controller interface. The structure_
   level argument is the address of a longword containing the
   version of the symbiont/job controller interface used when the
   symbiont was compiled. Always place the value of the symbol
   SMBMSG$K_STRUCTURE_LEVEL in the longword addressed by this
   argument. Each programming language provides an appropriate
   mechanism for defining symbols.
 

ast_routine

   OpenVMS usage:ast_procedure
   type:         procedure value
   access:       read only
   mechanism:    by reference
   Message-handling routine called at AST level. The ast_routine
   argument is the address of the entry point of the message-
   handling routine to be called at AST level when the symbiont
   receives a message from the job controller. The AST routine is
   called with no parameters and returns no value. If an AST routine
   is specified, the routine is called once each time the symbiont
   receives a message from the job controller.

   The AST routine typically reads the message and determines if
   immediate action must be taken. Be aware that an AST can be
   delivered only while the symbiont is operating at non-AST level.
   Thus, to ensure delivery of messages from the job controller, the
   symbiont should not perform lengthy operations at AST level.

   If you do not specify the ast_routine argument, the symbiont
   must call the SMB$CHECK_FOR_MESSAGE routine to check for waiting
   messages.
 

streams

   OpenVMS usage:longword_unsigned
   type:         longword (unsigned)
   access:       read only
   mechanism:    by reference
   Maximum number of streams the symbiont is to support. The streams
   argument is the address of a longword containing the number of
   streams that the symbiont is to support. The number must be in
   the range of 1 to 32.

   If you do not specify this argument, a default value of 1 is
   used. Thus, by default, a symbiont supports one stream. Such a
   symbiont is called a single-threaded symbiont.

   A stream (or thread) is a logical link between a queue and a
   symbiont. When a symbiont is linked to more than one queue, and
   serves those queues simultaneously, it is called a multithreaded
   symbiont.
 

3  Description
   Your symbiont must call SMB$INITIALIZE before calling any
   other SMB routines. It calls SMB$INITIALIZE in order to do the
   following:

   o  Allocate and initialize the SMB facility's internal database.

   o  Establish the interface between the job controller and the
      symbiont.

   o  Determine the threading scheme of the symbiont.

   o  Set up the mechanism to wake your symbiont when a message is
      received.

   After the symbiont calls SMB$INITIALIZE, it can communicate with
   the job controller using the other SMB routines.
 

3  Condition_Values_Returned

   SS$_NORMAL         Normal successful completion.
   SMB$_INVSTRLEV     Invalid structure level.

   This routine also returns any codes returned by $ASSIGN and
   LIB$GET_VM.
 

2  SMB$READ_MESSAGE
   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
 

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

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

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

2  SMB$READ_MESSAGE_ITEM
   The SMB$READ_MESSAGE_ITEM routine reads a buffer that was filled
   in by the SMB$READ_MESSAGE routine, parses one message item from
   the buffer, writes the item's code into a longword, and writes
   the item into a buffer.

   Format

     SMB$READ_MESSAGE_ITEM  message ,context ,item_code ,buffer

                            [,size]
 

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

3  Arguments
 

message

   OpenVMS usage:char_string
   type:         character string
   access:       read only
   mechanism:    by descriptor
   Message items that SMB$READ_MESSAGE_ITEM is to read. The message
   argument is the address of a descriptor of a buffer. The buffer
   is the one that contains the message items that SMB$READ_MESSAGE_
   ITEM is to read. The buffer specified here must be the same as
   that specified with the call to the SMB$READ_MESSAGE routine,
   which fills the buffer with the contents of the message.
 

context

   OpenVMS usage:context
   type:         longword (unsigned)
   access:       modify
   mechanism:    by reference
   Value initialized to 0 specifying the first message item in
   the buffer to be read. The context argument is the address of a
   longword that the SMB$READ_MESSAGE_ITEM routine uses to determine
   the next message item to be returned. When this value is 0,
   it indicates that SMB$READ_MESSAGE_ITEM is to return the first
   message item.

   The SMB$READ_MESSAGE_ITEM routine updates this value each time it
   reads a message item. SMB$READ_MESSAGE_ITEM sets the value to 0
   when it has returned all the message items in the buffer.
 

item_code

   OpenVMS usage:smb_item
   type:         longword (unsigned)
   access:       write only
   mechanism:    by reference
   Item code specified in the message item that identifies its type.
   The item_code argument is the address of a longword into which
   SMB$READ_MESSAGE_ITEM writes the code that identifies which item
   it is returning.

   The codes that identify message items are defined at the end of
   the Description help topic for this routine.
 

buffer

   OpenVMS usage:char_string
   type:         character string
   access:       write only
   mechanism:    by descriptor
   Message item. The buffer argument is the address of a descriptor
   of a buffer. The buffer is the one in which the SMB$READ_MESSAGE_
   ITEM routine is to place the message item data. SMB$READ_MESSAGE_
   ITEM uses the Run-Time Library string-handling (STR$) routines to
   copy the message item data into the buffer.
 

size

   OpenVMS usage:word_unsigned
   type:         word (unsigned)
   access:       write only
   mechanism:    by reference
   Size of the message item. The size argument is the address of a
   word in which the SMB$READ_MESSAGE_ITEM is to place the size, in
   bytes, of the item's data.
 

3  Description
   The job controller can request seven functions from the symbiont.
   They are identified by the following codes:

   SMBMSG$K_START_STREAM       SMBMSG$K_STOP_STREAM
   SMBMSG$K_START_TASK         SMBMSG$K_PAUSE_TASK
   SMBMSG$K_RESUME_TASK        SMBMSG$K_STOP_TASK
   SMBMSG$K_RESET_STREAM

   The job controller passes the symbiont a request containing
   a code and, optionally, a number of message items containing
   information the symbiont might need to perform the function. The
   code specifies what function the request is for, and the message
   items contain information that the symbiont needs to carry out
   the function.

   By calling SMB$READ_MESSAGE, the symbiont reads the request
   and writes the message items into the specified buffer. The
   symbiont then obtains the individual message items by calling
   the SMB$READ_MESSAGE_ITEM routine.

   Each message item consists of a code that identifies the
   information the item represents, and the item itself. For
   example, the SMB$K_JOB_NAME code tells the symbiont that the
   item specifies a job's name.

   The number of items in a request varies with each type of
   request. Therefore, you must call SMB$READ_MESSAGE_ITEM
   repeatedly for each request to ensure that all message items
   are read. Each time SMB$READ_MESSAGE_ITEM reads a message item,
   it updates the value in the longword specified by the context
   argument. SMB$READ_MESSAGE_ITEM returns the code SMB$_NOMOREITEMS
   after it has read the last message item.

   The following table shows the message items that can be delivered
   with each request:

   Request               Message Item

   SMBMSG$K_START_TASK   SMBMSG$K_ACCOUNT_NAME
                         SMBMSG$K_AFTER_TIME
                         SMBMSG$K_BOTTOM_MARGIN
                         SMBMSG$K_CHARACTERISTICS
                         SMBMSG$K_CHECKPOINT_DATA
                         SMBMSG$K_ENTRY_NUMBER
                         SMBMSG$K_FILE_COPIES
                         SMBMSG$K_FILE_COUNT
                         SMBMSG$K_FILE_IDENTIFICATION
                         SMBMSG$K_FILE_SETUP_MODULES
                         SMBMSG$K_FILE_SPECIFICATION
                         SMBMSG$K_FIRST_PAGE
                         SMBMSG$K_FORM_LENGTH
                         SMBMSG$K_FORM_NAME
                         SMBMSG$K_FORM_SETUP_MODULES
                         SMBMSG$K_FORM_WIDTH
                         SMBMSG$K_JOB_COPIES
                         SMBMSG$K_JOB_COUNT
                         SMBMSG$K_JOB_NAME
                         SMBMSG$K_JOB_RESET_MODULES
                         SMBMSG$K_LAST_PAGE
                         SMBMSG$K_LEFT_MARGIN
                         SMBMSG$K_MESSAGE_VECTOR
                         SMBMSG$K_NOTE
                         SMBMSG$K_PAGE_SETUP_MODULES
                         SMBMSG$K_PARAMETER_1

                             .
                             .
                             .
                         SMBMSG$K_PARAMETER_8
                         SMBMSG$K_PRINT_CONTROL
                         SMBMSG$K_SEPARATION_CONTROL
                         SMBMSG$K_REQUEST_CONTROL
                         SMBMSG$K_PRIORITY
                         SMBMSG$K_QUEUE
                         SMBMSG$K_RIGHT_MARGIN
                         SMBMSG$K_TIME_QUEUED
                         SMBMSG$K_TOP_MARGIN
                         SMBMSG$K_UIC
                         SMBMSG$K_USER_NAME
   SMBMSG$K_STOP_TASK    SMBMSG$K_STOP_CONDITION
   SMBMSG$K_PAUSE_TASK   None
   SMBMSG$K_RESUME_      SMBMSG$K_ALIGNMENT_PAGES
   TASK
                         SMBMSG$K_RELATIVE_PAGE
                         SMBMSG$K_REQUEST_CONTROL
                         SMBMSG$K_SEARCH_STRING
   SMBMSG$K_START_       SMBMSG$K_DEVICE_NAME
   STREAM
                         SMBMSG$K_EXECUTOR_QUEUE
                         SMBMSG$K_JOB_RESET_MODULES
                         SMBMSG$K_LIBRARY_SPECIFICATION
   SMBMSG$K_STOP_        None
   STREAM
   SMBMSG$K_RESET_       None
   STREAM

   The following list describes each item code. For each code, the
   list describes the contents of the message item identified by
   the code and whether the code identifies an item sent from the
   job controller to the symbiont or from the symbiont to the job
   controller.

   Many of the codes described are specifically oriented toward
   print symbionts. The symbiont you implement, which might not
   print files or serve an output device, need not recognize all
   these codes. In addition, it need not respond in the same way as
   the print symbiont to the codes it recognizes. The descriptions
   in the list describe how the standard print symbiont (PRTSMB.EXE)
   processes these items.

                                  NOTE

      Because new codes might be added in the future, you should
      write your symbiont so that it ignores codes it does not
      recognize.
 

3  Codes_for_Message_Items
 

SMBMSG$K_ACCOUNT_NAME

   This code identifies a string containing the name of the account
   to be charged for the job, that is, the account of the process
   that submitted the print job.
 

SMBMSG$K_AFTER_TIME

   This code identifies a 64-bit, absolute-time value specifying the
   system time after which the job controller can process this job.
 

SMBMSG$K_ALIGNMENT_PAGES

   This code identifies a longword specifying the number of
   alignment pages that the symbiont is to print.
 

SMBMSG$K_BOTTOM_MARGIN

   This code identifies a longword containing the number of lines to
   be left blank at the bottom of a page.

   The symbiont inserts a form feed character into the output stream
   if it determines that all of the following conditions are true:

   o  The number of lines left at the bottom of the page is equal to
      the value in SMBMSG$K_BOTTOM_MARGIN.

   o  Sending more data to the printer to be output on this page
      would cause characters to be printed within this bottom margin
      of the page.

   o  The /FEED qualifier was specified with the PRINT command that
      caused the symbiont to perform this task.

   (Line feed, form feed, carriage-return, and vertical-tab
   characters in the output stream are collectively known as
   embedded carriage control.)
 

SMBMSG$K_CHARACTERISTICS

   This code identifies a 16-byte structure specifying
   characteristics of the job. A detailed description of the format
   of this structure is contained in the description of the QUI$_
   CHARACTERISTICS code in the $GETQUI system service in the VSI
   OpenVMS System Services Reference Manual.
 

SMBMSG$K_DEVICE_NAME

   This code identifies a string that is the name of the device to
   which the symbiont is to send data. The symbiont interprets this
   information. The name need not be the name of a physical device,
   and the symbiont can interpret this string as something other
   than the name of a device.
 

SMBMSG$K_ENTRY_NUMBER

   This code identifies a longword containing the number that the
   job controller assigned to the job.
 

SMBMSG$K_EXECUTOR_QUEUE

   This code identifies a string that is the name of the queue on
   which the symbiont stream is to be started.
 

SMBMSG$K_FILE_COPIES

   This code identifies a longword containing the number of copies
   of the file that were requested.
 

SMBMSG$K_FILE_COUNT

   This code identifies a longword that specifies, out of the number
   of copies requested for this job (SMBMSG$K_FILE_COPIES), the
   number of the copy of the file currently printing.
 

SMBMSG$K_FILE_IDENTIFICATION

   This code identifies a 28-byte structure identifying the file
   to be processed. This structure consists of the following three
   file-identification fields in the OpenVMS RMS NAM block:

   1. The 16-byte NAM$T_DVI field

   2. The 6-byte NAM$W_FID field

   3. The 6-byte NAM$W_DID field

   These fields occur consecutively in the NAM block in the order
   listed.
 

SMBMSG$K_FILE_SETUP_MODULES

   This code identifies a string specifying the names (separated by
   commas) of one or more text modules that the symbiont should copy
   from the library into the output stream before processing the
   file.
 

SMBMSG$K_FILE_SPECIFICATION

   This code identifies a string specifying the name of the file
   that the symbiont is to process. This file name is formatted as a
   standard RMS file specification.
 

SMBMSG$K_FIRST_PAGE

   This code identifies a longword containing the number of the page
   at which the symbiont should begin printing. The job controller
   sends this item to the symbiont. When not specified, the symbiont
   begins processing at page 1.
 

SMBMSG$K_FORM_LENGTH

   This code identifies a longword value specifying the length (in
   lines) of the physical form (the paper).
 

SMBMSG$K_FORM_NAME

   This code identifies a string specifying the name of the form.
 

SMBMSG$K_FORM_SETUP_MODULES

   This code identifies a string consisting of the names (separated
   by commas) of one or more modules that the symbiont should copy
   from the device-control library before processing the file.
 

SMBMSG$K_FORM_WIDTH

   This code identifies a longword specifying the width (in
   characters) of the print area on the physical form (the paper).
 

SMBMSG$K_JOB_COPIES

   This code identifies a longword specifying the requested number
   of copies of the job.
 

SMBMSG$K_JOB_COUNT

   This code identifies a longword specifying, out of the number of
   copies requested (SMBMSG$K_JOB_COPIES), the number of the copy of
   the job currently printing.
 

SMBMSG$K_JOB_NAME

   This code identifies a string specifying the name of the job.
 

SMBMSG$K_JOB_RESET_MODULES

   This code identifies a string specifying a list of one or more
   module names (separated by commas) that the symbiont should copy
   from the device-control library after processing the task. These
   modules can be used to reset programmable devices to a known
   state.
 

SMBMSG$K_LAST_PAGE

   This code identifies a longword specifying the number of the
   last page that the symbiont is to print. When not specified, the
   symbiont attempts to print all the pages in the file.
 

SMBMSG$K_LEFT_MARGIN

   This code identifies a longword specifying the number of spaces
   to be inserted at the beginning of each line.
 

SMBMSG$K_LIBRARY_SPECIFICATION

   This code identifies a string specifying the name of the device-
   control library.
 

SMBMSG$K_MESSAGE_VECTOR

   This code identifies a vector of longword condition codes, each
   of which contains information about the job to be printed.

   When LOGINOUT cannot open a log file for a batch job, a code in
   the message vector specifies the reason for the failure. The job
   controller does not send the SMBMSG$K_FILE_IDENTIFICATION item
   if it has detected such a failure but instead sends the message
   vector, which the symbiont prints, along with a message stating
   that there is no file to print.
 

SMBMSG$K_NOTE

   This code identifies a user-supplied string that the symbiont is
   to print on the job flag page and on the file flag page.
 

SMBMSG$K_PAGE_SETUP_MODULES

   This code identifies a string consisting of the names (separated
   by commas) of one or more modules that the symbiont should copy
   from the device-control library before printing each page.
 

SMBMSG$K_PARAMETER_1 through SMBMSG$K_PARAMETER_8

   Each of these eight codes identifies a user-supplied string. Both
   the semantics and syntax of each string are determined by the
   user-defined symbiont. The OpenVMS-supplied symbiont makes no use
   of these eight items.
 

SMBMSG$K_PRINT_CONTROL

   This code identifies a longword bit vector, each bit of which
   supplies information that the symbiont is to use in controlling
   the printing of the file.

   Symbol                    Description

   SMBMSG$V_DOUBLE_SPACE     The symbiont uses a double-spaced
                             format; it skips a line after each
                             line it prints.
   SMBMSG$V_NO_INITIAL_FF    The symbiont suppresses the initial
                             form feed if this bit is turned on.
   SMBMSG$V_NORECORD_        The symbiont performs single record
   BLOCKING                  output, issuing a single output record
                             for each input record.
   SMBMSG$V_PAGE_HEADER      The symbiont prints a page header at
                             the top of each page.
   SMBMSG$V_PAGINATE         The symbiont inserts a form feed
                             character when it detects an attempt
                             to print in the bottom margin of the
                             current form.
   SMBMSG$V_PASSALL          The symbiont prints the file without
                             formatting and bypasses all formatting
                             normally performed. Furthermore, the
                             symbiont outputs the file without
                             formatting, by causing the output QIO
                             to suppress formatting by the driver.
   SMBMSG$V_RECORD_BLOCKING  The symbiont performs record blocking,
                             buffering output to the device.
   SMBMSG$V_SEQUENCED        This bit is reserved by VSI.
   SMBMSG$V_SHEET_FEED       The symbiont pauses the queue after
                             each page it prints.
   SMBMSG$V_TRUNCATE         The symbiont truncates input lines that
                             exceed the right margin of the current
                             form.
   SMBMSG$V_WRAP             The symbiont wraps input lines that
                             exceed the right margin, printing the
                             additional characters on a new line.
 

SMBMSG$K_PRIORITY

   This code identifies a longword specifying the priority this job
   has in the queue in which it is entered.
 

SMBMSG$K_QUEUE

   This code identifies a string specifying the name of the queue
   in which this job is entered. When generic queues are used, this
   item specifies the name of the generic queue, and the SMBMSG$K_
   EXECUTOR item specifies the name of the device queue or the
   server queue.
 

SMBMSG$K_RELATIVE_PAGE

   This code identifies a signed, longword value specifying the
   number of pages that the symbiont is to move forward (positive
   value) or backward (negative value) from the current position in
   the file.
 

SMBMSG$K_REQUEST_CONTROL

   This code identifies a longword bit vector, each bit of which
   specifies information that the symbiont is to use in processing
   the request that the job controller is making.

   Symbol                    Description

   SMBMSG$V_ALIGNMENT_MASK   The symbiont is to replace all
                             alphabetic characters with the
                             letter X, and all numeric characters
                             with the number 9. Other characters
                             (punctuation, carriage control, and
                             so on) are left unchanged. This bit is
                             ordinarily specified in connection with
                             the SMBMSG$K_ALIGNMENT_PAGES item.
   SMBMSG$V_PAUSE_COMPLETE   The symbiont is to pause when it
                             completes the current request.
   SMBMSG$V_RESTARTING       Indicates that this job was previously
                             interrupted and requeued, and is now
                             restarting.
   SMBMSG$V_TOP_OF_FILE      The symbiont is to rewind the input
                             file before it resumes printing.
 

SMBMSG$K_RIGHT_MARGIN

   This code identifies a longword specifying the number of
   character positions to be left empty at the end of each line.
   When the right margin is exceeded, the symbiont truncates the
   line, wraps the line, or continues processing, depending on the
   settings of the WRAP and TRUNCATE bits in the SMBMSG$K_PRINT_
   CONTROL item.
 

SMBMSG$K_SEARCH_STRING

   This code identifies a string containing the value specified in
   the START/QUEUE/SEARCH command. This string identifies the page
   at which to restart the current printing task on a paused queue.
 

SMBMSG$K_SEPARATION_CONTROL

   This code identifies a longword bit vector, each bit of which
   specifies an operation that the symbiont is to perform between
   jobs or between files within a job. The $SMBDEF macro defines the
   following symbols for each bit:

   Symbol                    Description

   SMBMSG$V_FILE_BURST       The symbiont is to print a file burst
                             page.
   SMBMSG$V_FILE_FLAG        The symbiont is to print a file flag
                             page.
   SMBMSG$V_FILE_TRAILER     The symbiont is to print a file trailer
                             page.
   SMBMSG$V_FILE_TRAILER_    The symbiont is to print a file trailer
   ABORT                     page when a task completes abnormally.
   SMBMSG$V_FIRST_FILE_OF_   The current file is the first file of
   JOB                       the job. When specified with SMBMSG$V_
                             LAST_FILE_OF_JOB, the current job
                             contains a single file.
   SMBMSG$V_JOB_FLAG         The symbiont is to print a job flag
                             page.
   SMBMSG$V_JOB_BURST        The symbiont is to print a job burst
                             page.
   SMBMSG$V_JOB_RESET        The symbiont is to execute a job reset
                             sequence when the task completes.
   SMBMSG$V_JOB_RESET_ABORT  The symbiont is to execute a job
                             reset sequence when a task completes
                             abnormally.
   SMBMSG$V_JOB_TRAILER      The symbiont is to print a job trailer
                             page.
   SMBMSG$V_JOB_TRAILER_     The symbiont is to print a job trailer
   ABORT                     page when a task completes abnormally.
   SMBMSG$V_LAST_FILE_OF_    The current file is the last file of
   JOB                       the job. When specified with SMBMSG$V_
                             FIRST_FILE_OF_JOB, the current job
                             contains a single job.
 

SMBMSG$K_STOP_CONDITION

   This code identifies a longword containing a condition specifying
   the reason the job controller issued a STOP_TASK request.
 

SMBMSG$K_TIME_QUEUED

   This code identifies a quadword specifying the time the file was
   entered into the queue. The time is expressed as 64-bit, absolute
   time.
 

SMBMSG$K_TOP_MARGIN

   This code identifies a longword specifying the number of lines
   that the symbiont is to leave blank at the top of each page.
   PRTSMB inserts line feeds into the output stream after every form
   feed until the margin is cleared.
 

SMBMSG$K_UIC

   This code identifies a longword specifying the user
   identification code (UIC) of the user who submitted the job.
 

SMBMSG$K_USER_NAME

   This code identifies a string specifying the name of the user who
   submitted the job.
 

3  Condition_Values_Returned

   SS$_NORMAL         Normal successful completion.
   SMB$_NOMOREITEMS   End of item list reached.

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

2  SMB$SEND_TO_JOBCTL
   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]
 

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

3  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 help topic.)
 

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:

   31                                                  0
   -----------------------------------------------------
            Number of pages printed for the job
   -----------------------------------------------------
             Number of reads from disk or tape
   -----------------------------------------------------
          Number of writes to the printing device
   -----------------------------------------------------
                          Unused
   -----------------------------------------------------
 

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 (See footnote.)

   Footnote: This is usually the value specified in the SMBMSG$K_
   STOP_CONDITION item that was sent by the job controller with the
   SMBMSG$K_STOP_TASK request.)

   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.
 

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

