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.