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