Updated: 11 December 1998 |
OpenVMS Utility Routines Manual
Previous | Contents | Index |
This routine also returns any error condition values that you have coded your format routine to return. Refer to Section 15.3.1 for more information about error condition values.
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.
USER-OUTPUT-ROUTINE request_id ,work_area ,func ,funcdesc ,funcarg
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.
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.
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:
- Can print lowercase letters
- Is a terminal
- 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. Compaq 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. Compaq 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:
- 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.
- 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, which are discussed in more detail in Section 16.1.6, 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.
OpenVMS usage: | char_string |
type: | character string |
access: | read only |
mechanism: | by 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.
OpenVMS usage: | user_arg |
type: | longword (unsigned) |
access: | read only |
mechanism: | by reference |
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.
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. Refer to Section 15.3.1 for more information about error condition values.
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.
16.1 Introduction to SMB Routines
Always use the SMB interface routines or the $SNDJBC or $GETQUI system services to communicate with the job controller. You need not and should not attempt to communicate directly with the job controller.
To write your own symbiont, you need to understand how symbionts work
and, in particular, how the standard print symbiont behaves.
16.1.1 Types of Symbiont
There are two types of symbiont:
The operating system does not supply any server symbionts.
16.1.2 Symbionts Supplied with the Operating System
The operating system supplies two symbionts:
In the OpenVMS environment, a symbiont is a process under the control of the job controller that transfers or processes data.
Figure 16-1 depicts the components that take part in the handling of user requests that involve symbionts. This figure shows two symbionts: (1) the print symbiont supplied by the operating system, PRTSMB, and (2) a user-written symbiont, GRAPHICS.EXE, which services a graphics plotter. The numbers in the figure correspond to the numbers in the list that follows.
This list does not reflect the activities that must be performed by the hypothetical, user-written symbiont, GRAPHICS.EXE. This symbiont is represented in the figure to illustrate the correspondence between a user-written symbiont and the print symbiont supplied by the operating system.
Although SMB routines can be used for a different kind of symbiont, many of their arguments and associated symbols have names related to the print symbiont. The print symbiont is presented here as an example of a typical symbiont and illustrates points that are generally true for symbionts.
Figure 16-1 Symbionts in the OpenVMS Environment
Writing your own symbiont permits you to use the queuing mechanisms and control functions of the job controller. You might want to do this if you need a symbiont for a device that cannot be served by PRTSMB (or a modified form of PRTSMB) or if you need a server symbiont. The interface between the job controller and the symbiont permits the symbiont you write to use the many features of the job controller.
For example, when you use the DCL command PRINT, the job controller sends a message to the print symbiont telling it to print the file. However, when a user-written symbiont receives the same message (caused by entering a PRINT command), it might interpret it to mean something quite different. A robot symbiont, for example, might interpret the message as a command for movement and the file specification (specified with the PRINT command) might be a file describing the directions in which the robot is to move.
Modifying PRTSMB is easier than writing your own symbiont; choose this option if possible. The Print Symbiont Modification (PSM) routines describe how to modify PRTSMB to suit your needs. |
Although you can write a symbiont to use the queuing mechanisms and other features of the job controller in whatever way you want, you must follow these guidelines to ensure that your symbiont works correctly:
The five SMB routines form a public interface to the job controller. The job controller delivers requests to symbionts by means of this interface, and the symbionts communicate their responses to those requests through this interface. A user-written symbiont uses the following routines to exchange messages with the job controller:
Routine | Description |
---|---|
SMB$INITIALIZE |
Initializes the SMB facility's internal database, establishes the
interface to the job controller, and defines whether:
|
SMB$CHECK_FOR_MESSAGE | Checks to see if a message from the job controller to the symbiont has arrived (used with synchronous symbionts) |
SMB$READ_MESSAGE | Reads the job controller's message into a buffer |
SMB$READ_MESSAGE_ITEM | Returns one item of information from the job controller's message (which can have several informational items) |
SMB$SEND_TO_JOBCTL | Sends a message from the symbiont to the job controller |
The following sections discuss how to use the SMB routines when writing
your symbiont.
16.1.7 Choosing the Symbiont Environment
The first SMB routine that a symbiont must call is the SMB$INITIALIZE routine. In addition to allocating and initializing the SMB facility's internal database, it offers you two options for your symbiont environment: (1) synchronous or asynchonous delivery of messages from the job controller, and (2) single streaming or multistreaming the symbiont.
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4493PRO_046.HTML
|