FILTER), which executes after the main format routine, uses neither the func_arg_1 nor func_arg_2 argument; the data it receives (via func_desc_1) and the data it returns (via func_ desc_2) are data streams, not data records. However, the input filter routine (routine code PSM$K_INPUT_ FILTER), which executes before the main format routine, uses both func_arg_1 and func_arg_2. This is so because the main format routine has not yet executed, and so the carriage control information has not yet been embedded in the data record. 3 Condition_Values_Returned SS$_NORMAL Successful completion. The user format routine has completed the function that the symbiont requested. PSM$_FUNNOTSUP Function not supported. The user format routine does not support or does not recognize the function code supplied by the symbiont. To ensure future compatibility, your format routine should return this status for any unrecognized status codes. This routine also returns any error condition values that you have coded your format routine to return. 2 USER-INPUT-ROUTINE The user-written USER-INPUT-ROUTINE performs input operations. The symbiont calls your routine at a specified point in its execution stream; you specify this point using the PSM$REPLACE routine. Format USER-INPUT-ROUTINE request_id ,work_area ,func ,funcdesc ,funcarg 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 request_id OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Request identifier value supplied by the symbiont when it calls your input routine. The request_id argument is the address of a longword containing this request identifier value. If your input routine initiates an asynchronous operation (for example, a call to the $QIO system service), your input routine must copy the request identifier value specified by request_ id because this value must later be passed to the PSM$REPORT routine. See the description of the PSM$REPORT routine for more information. work_area OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Work area supplied by the symbiont for the use of your input routine. The symbiont supplies the address of this area when it calls your routine. The work_area argument is a longword into which the symbiont writes the address of the work area. The work area is a section of memory that your input routine can use for buffering and for other internal operations. The size of the work area allocated is specified by the work_size argument in the PSM$PRINT routine. If you do not specify work_ size in the call to PSM$PRINT, no work area is allocated. In a multithreaded symbiont, a separate work area is allocated for each thread. This work area is shared by all user routines. The work area is initialized to zero when the symbiont is first started. func OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference Function code supplied by the symbiont when it calls your input routine. The func argument is the address of a longword containing this code. The function code specifies the reason the symbiont is calling your input routine or, in other words, the function that the symbiont expects your routine to perform at this time. Most function codes require or allow additional information to be passed in the call by means of the funcdesc and funcarg arguments. The description of each input function code, therefore, includes a description of how these two arguments are used with that function code. Following is a list of all the function codes that the symbiont can specify when it calls your input routine (function codes applicable only to format and output routines are explained in the descriptions of the USER-FORMAT-ROUTINE and USER-OUTPUT- ROUTINE, respectively); all function codes are defined by the $PSMDEF macro. 3 Function_Codes_for_Input_Routines PSM$K_CLOSE When the symbiont calls your routine with this function code, your routine must terminate processing by releasing any resources it might have allocated. The symbiont calls your routine with PSM$K_CLOSE when (1) your routine returns from a PSM$K_READ function call with the status PSM$_EOF (end of input) or with any error condition, or (2) the symbiont receives a task-abortion request from the job controller. In any event, the symbiont always calls your input routine with PSM$K_CLOSE if your routine returns successfully from a PSM$K_OPEN function call. This guaranteed behavior ensures that any resources your routine might have allocated on the OPEN will be released on the CLOSE. PSM$K_GET_KEY Typically, the use of both the PSM$K_GET_KEY and PSMK$K_POSITION_ TO_KEY function codes is appropriate only for a main input routine (routine code PSM$K_MAIN_INPUT). When the symbiont calls your routine with this function code, your routine can do one of two things: (1) return PSM$_FUNNOTSUP (function not supported) or (2) return an input marker string to the symbiont. If your routine returns PSM$_FUNNOTSUP to this function code, then your routine must also return PSM$_FUNNOTSUP if the symbiont subsequently calls your routine with the PSM$K_POSITION_TO_KEY function code. By returning PSM$_FUNNOTSUP, your routine is choosing not to respond to the symbiont request. If your routine chooses to respond to the PSM$K_GET_KEY function code, your routine must return an input marker string to the symbiont; this input marker string identifies the input record that your input routine most recently returned to the symbiont. Subsequently, when the symbiont calls your input routine with the PSM$K_POSITION_TO_KEY function code, the symbiont passes your input routine one of the input marker strings that your input routine has returned on a previous PSM$K_GET_KEY function call. Using this marker string, your input routine must position itself so that, on the next PSM$K_READ call from the symbiont, your input routine will return (or reread) the input record identified by the marker string. Coding your input routine to respond to PSM$K_GET_KEY and PSM$K_POSITION_TO_KEY allows the modified symbiont to perform the file-positioning functions specified by the DCL commands START/QUEUE/FORWARD, START/QUEUE/ALIGN, START/QUEUE/TOP_OF_ FILE, START/QUEUE/SEARCH, and START/QUEUE/BACKWARD. These file positioning functions also depend on the job controller's checkpointing capability for print jobs. Note that your input routine might be called with a marker string that was originally returned in a different process context from the current one. This can occur because marker strings are sometimes stored in the queue-data file across system shutdowns or different invocations of your symbiont. The funcdesc argument specifies the address of a string descriptor. Your routine must return the marker string by way of this argument. VSI recommends that you use one of the Run- Time Library string routines to copy the marker string to the descriptor. The symbiont periodically calls your input routine with the PSM$K_GET_KEY function code when the symbiont wants to save a marker to a particular input record. PSM$K_OPEN When the symbiont calls your routine with this function code, your routine should prepare for input operations by performing such tasks as allocating necessary resources, initializing storage areas, opening an input file, and so on. Typically, the next time the symbiont calls your input routine, the symbiont will specify the PSM$K_READ function code. Note, however, that under some circumstances the symbiont might follow an OPEN call immediately with a CLOSE call. The funcdesc argument points to the name of the file to be opened. Your routine can use this file specification or the file identification to open the file. The funcarg argument specifies the address of a longword. Your input routine must return, in this longword, the carriage control type that is to be applied to the input records that your input routine will provide. The symbiont formatting routine requires this information to determine where to apply leading and trailing carriage control characters to the input records that your input routine will provide. The $PSMDEF macro defines the following four carriage control types: Carriage Control Type Description PSM$K_CC_ Implied carriage control. For this type, the IMPLIED symbiont inserts a leading line feed (LF) and trailing carriage return (CR) in each input record. This is the default carriage control type; it is used if your routine does not supply a carriage control type in the funcarg argument in response to the PSM$K_OPEN function call. PSM$K_CC_ Fortran carriage control. For this type, the FORTRAN symbiont extracts the first byte of each input record and interprets the byte as a Fortran carriage control character, which it then applies to the input record. PSM$K_CC_PRINT PRN carriage control. For this type, the symbiont generates carriage control from a 2-byte record header that your input routine supplies, with each READ call, in the funcarg argument. The funcarg argument specifies the address of a longword to receive this 2-byte header record, which appears only in PRN print files. PSM$K_CC_ Embedded carriage control. For this type, the INTERNAL symbiont supplies no carriage control to input records. Carriage control is assumed to be embedded in the input records. PSM$K_POSITION_TO_KEY When the symbiont calls your routine with this function code, your routine must locate the point in the input stream designated by the marker string that your routine returned to the symbiont on the PSM$K_GET_KEY function call. The next time the symbiont calls your routine, the symbiont specifies the PSM$K_READ function call, expecting to receive the next sequential input record. After rereading this record, subsequent READ calls proceed from this new position of the file. This is not a one-time rereading of a single record but a repositioning of the file. The symbiont calls your routine with this function code when the job controller receives a request to resume printing at a particular page. Refer to the description of the PSM$K_GET_KEY for more information. PSM$K_READ When the symbiont calls your routine with this function code, your routine must return an input record. The symbiont repeatedly calls your input routine with the PSM$K_READ function code until: (1) your routine indicates end of input by returning the status PSM$_EOF, (2) your routine or another routine returns an error status, or (3) the symbiont receives an asynchronous task-abortion request from the job controller. The funcdesc argument specifies the address of a string descriptor. Your routine must return the input record by using this argument. VSI recommends that you use one of the Run- Time Library string routines to copy the input record to the descriptor. The funcarg argument specifies the address of a longword. This argument is used only if the carriage control type returned by your input routine on the PSM$K_OPEN function call was PSM$K_ CC_PRINT. In this case, your input routine must supply, in the funcarg argument, the 2-byte record header found at the beginning of each input record. PSM$K_REWIND When the symbiont calls your routine with this function code, your routine must do one of two things: (1) return PSM$_ FUNNOTSUP (function not supported) or (2) locate the point in the input stream designated as the beginning of the file. If your routine returns PSM$_FUNNOTSUP to this function code, then the symbiont subsequently calls your input routine with a PSM$K_CLOSE function call followed by a PSM$K_OPEN function call. By returning PSM$_FUNNOTSUP, your routine is choosing not to support the repositioning of the input service to the beginning of the file. The symbiont, therefore, performs the desired function by closing and then reopening the input routine. You cannot use the funcdesc and the funcarg arguments with this function code. This function call allows the modified symbiont to perform the file-positioning functions specified by the DCL commands START/QUEUE/TOP_OF_FILE, START/QUEUE/FORWARD, START/QUEUE/BACKWARD, START/QUEUE/SEARCH, and START/QUEUE/ALIGN. This is a required repositioning of the file. Other Input Function Codes The symbiont can call your input routine with other function codes. Your routine must return the status PSM$_FUNNOTSUP (function not supported) when it is called with any of the following function codes or with any undocumented function code. When the status PSM$_FUNNOTSUP is returned, the symbiont performs its normal action as if no input routine were supplied. To suppress the symbiont's normal action, you should return SS$_ NORMAL. PSM$K_START_STREAM PSM$K_STOP_STREAM PSM$K_START_TASK PSM$K_PAUSE_TASK PSM$K_RESUME_TASK PSM$K_STOP_TASK PSM$K_RESET_STREAM These function codes correspond to message items sent by the job controller to the symbiont. Other function codes correspond to internal symbiont mechanisms that are not part of the public interface to the print symbiont. Your input routine should return the status PSM$_FUNNOTSUP or SS$_NORMAL when it is called with a message function code or with a private function code. funcdesc OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Function descriptor supplying information related to the function specified by the func argument. The funcdesc argument is the address of this descriptor. The contents of the function descriptor can vary for each function. Refer to the description of each function code to determine the contents of the function descriptor. In some cases, the function descriptor is not used at all. funcarg OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Function argument supplying information related to the function specified by the func argument. The funcarg argument is the address of a longword containing this function argument. This argument can be an input or an output argument, depending on the function request, but is usually used as an output argument. 3 Condition_Values_Returned SS$_NORMAL Successful completion. The user input routine has completed the function that the symbiont requested. PSM$_FLUSH Flush output stream. The user input routine can return this status only when called with the PSM$K_READ function code. When this status is returned to the symbiont, the symbiont stops calling the input routine with the PSM$K_READ function code until all outstanding format and output operations have completed. PSM$_FUNNOTSUP Function not supported. The user input routine does not support or does not recognize the function code supplied by the symbiont. To ensure future compatibility, your input routine should return this status for any unrecognized status codes. PSM$_PENDING Requested function accepted but not completed. Your input routine can return this status only with the PSM$K_READ function call. Further, if your routine returns PSM$_PENDING, your routine must eventually signal completion via the PSM$REPORT routine. Refer to the description of the PSM$REPORT routine for more information about asynchronous operations and the PSM$_PENDING condition value. This routine also returns any error condition values that you have coded your format routine to return. 2 USER-OUTPUT-ROUTINE The user-written USER-OUTPUT-ROUTINE performs output operations. You supply a user output routine by calling the PSM$REPLACE routine with the routine code PSM$K_OUTPUT. Format USER-OUTPUT-ROUTINE request_id ,work_area ,func ,funcdesc ,funcarg 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 request_id OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Request identifier value supplied by the symbiont when it calls your output routine. The request_id argument is the address of a longword containing this value. If your output routine initiates an asynchronous operation (for example, a call to the $QIO system service), you must save the request_id argument because you will need to store the request identifier value for later use with the PSM$REPORT routine. See the description of the PSM$REPORT routine for more information. work_area OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Work area supplied by the symbiont for the use of your format routine. The symbiont supplies the address of this area when it calls your routine. The work_area argument is a longword containing the address of the work area. The work area is a section of memory that your format routine can use for buffering and other internal operations. The size of the work area allocated is specified by the work_size argument in the PSM$PRINT routine. If you do not specify work_ size in the call to PSM$PRINT, no work area is allocated. In a multithreaded symbiont, a separate work area is allocated for each thread. This work area is shared by all user routines. The work area is initialized to zero when the symbiont is first started. func OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference Function code supplied by the symbiont when it calls your output routine. The func argument is the address of a longword containing this code. The function code specifies the reason the symbiont is calling your output routine or, in other words, the function that the symbiont expects your routine to perform at this time. Most function codes require or allow additional information to be passed in the call via the funcdesc and funcarg arguments. The description of each output function code, therefore, includes a description of how these two arguments are used for that function code. The following list describes all the function codes that the symbiont might supply when it calls your output routine (function codes applicable only to input and formatting routines are explained in the descriptions of the user input routine and user formatting routine, respectively). Each programming language provides an appropriate mechanism for defining these function codes. 3 Function_Codes_for_Output_Routines PSM$K_OPEN When the symbiont calls your output routine with this function code, your routine should prepare to move data to the device by performing such tasks as allocating the device, assigning a channel to the device, and so on. The next time the symbiont calls your output routine, the symbiont specifies one of the WRITE function codes (PSM$K_WRITE or PSM$K_WRITE_NOFORMAT). The symbiont calls your output routine with the PSM$K_OPEN function code when the symbiont receives the SMBMSG$K_START_ STREAM message from the job controller. If your output routine returns an error condition value (low bit clear) to the PSM$K_OPEN function call, the job controller stops processing on the stream and reports the error to whomever entered the DCL command START/QUEUE. The funcdesc argument is the address of a descriptor that identifies the name of the device to which the output routine is to write. This device name is established by the DCL command INITIALIZE/QUEUE/ON=device. The funcarg argument is the address of a longword into which the user output routine returns the device status longword. Your output routine sets bits in the device status longword to indicate to the job controller whether the device falls into one of the following categories: o Can print lowercase letters o Is a terminal o Is connected to the CPU by means of a modem (remote) If your output routine does not set any of these bits in the device status longword, the job controller assumes, by default, that the device is a line printer that prints only uppercase letters. PSM$K_WRITE When the symbiont calls your routine with this function code, your routine must write data to the device. The symbiont supplies the data to be written in the funcdesc argument. VSI recommends that you use one of the Run-Time Library string routines to access the data in the buffer described by the funcdesc argument. PSM$K_WRITE_NOFORMAT When the symbiont calls your routine with this function code, your routine must write data to the device and must indicate to the device driver that the data is not to be formatted. The symbiont calls your routine with this function code when: (1) the print request specifies the PASSALL option or (2) data is introduced by the ANSI DCS (device control string) escape sequence. The symbiont supplies the data to be written in the funcdesc argument. VSI recommends that you use one of the Run-Time Library string routines to move the data from the descriptor to the device. The output routine of the symbiont informs the device driver not to format the data in the following way: o When the device is a line printer, the symbiont's output routine specifies the IO$_WRITEPBLK function code when it calls the $QIO system service. o When the device is a terminal, the symbiont's output routine specifies the IO$M_NOFORMAT function modifier when it calls the $QIO system serivce. PSM$K_CANCEL When the symbiont calls your routine with this function code, your routine must abort any outstanding asynchronous I/O requests. The output routine supplied by the symbiont aborts outstanding I/O requests by calling the $CANCEL system service with the IO$_ CANCEL function code. If your output routine returned the condition value PSM$_ PENDING to one or more previous write requests that are still outstanding (that is, PSM$REPORT has not yet been called to report completion), then your output routine must call PSM$REPORT one time for each outstanding write request that is canceled with this call. That is, canceling an asynchronous write request does not relieve the user output routine of the requirement to call PSM$REPORT once for each asynchronous write request. You cannot use the funcdesc and funcarg arguments with this function code. PSM$K_CLOSE When the symbiont calls your routine with this function code, your output routine must terminate processing and release any resources it allocated (for example, channels assigned to the device). You cannot use the funcdesc and funcarg arguments with this function code. Other Output Function Codes The symbiont can call your output routine with other function codes. Your routine should return the status PSM$_FUNNOTSUP (function not supported) when it is called with any of the following function codes or with any undocumented function code. When the status PSM$_FUNNOTSUP is returned, the symbiont performs its normal action as if no output routine were supplied. To suppress the symbiont's normal action, you should return SS$_ NORMAL. PSM$K_START_STREAM PSM$K_STOP_STREAM PSM$K_START_TASK PSM$K_PAUSE_TASK PSM$K_RESUME_TASK PSM$K_STOP_TASK PSM$K_RESET_STREAM These function codes correspond to message items sent by the job controller to the symbiont. Other function codes correspond to internal symbiont mechanisms that are not part of the public interface to the print symbiont. Your output routine should return the status PSM$_FUNNOTSUP or SS$_NORMAL when it is called with a message function code or with a private function code. funcdesc OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Function descriptor supplying information related to the function specified by the func argument. The funcdesc argument is the address of this descriptor. The contents of the function descriptor can vary for each function. Refer to the description of each function code to determine the contents of the function descriptor. In some cases, the function descriptor is not used at all. funcarg OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by reference Function argument supplying information related to the function specified by the func argument. The funcarg argument is the address of a longword containing this function argument. The contents of the function argument can vary for each function. Refer to the description of each function code to determine the contents of the function argument. In some cases, the function argument is not used. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. The user output routine has completed the function that the symbiont requested. PSM$_FUNNOTSUP Function not supported. The user output routine does not support or does not recognize the function code supplied by the symbiont. To ensure future compatibility, your output routine should return this status for any unrecognized status codes. PSM$_PENDING Requested function accepted but not completed. Your output routine can return this status only with PSM$K_WRITE and PSM$K_WRITE_NOFORMAT function calls. Further, if your routine returns PSM$_PENDING, your routine must eventually signal completion by way of the PSM$REPORT routine. Refer to the description of the PSM$REPORT routine for more information about asynchronous write operations and the PSM$_PENDING condition value. This routine also returns any error condition values that you have coded your output routine to return.