HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

This section describes the individual PSM routines.

The PSM$PRINT routine invokes the OpenVMS-supplied print symbiont.

PSM$PRINT must be called exactly once after all user service routines have been specified using PSM$REPLACE.

Format

PSM$PRINT [streams] [,bufsiz] [,worksiz] [,maxqios] [,options]

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.

Arguments

streams

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Maximum number of streams that the symbiont is to support. The streams argument is the address of a longword containing this number, which must be in the range of 1 to 16. If you do not specify streams, a default value of 1 is used. Thus, by default, a user-modified symbiont supports one stream, which is to say that it is a single-threaded symbiont.

A stream (or thread) is a logical link between a print execution queue and a printing device. When a symbiont process can accept simultaneous links to more than one queue, that is, when it can service multiple queues simultaneously, the symbiont is said to be multithreaded.

bufsiz

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Maximum buffer size in bytes that the print symbiont is to use for output operations. The bufsiz argument is the address of a longword containing the specified number of bytes.

The print symbiont actually uses a buffer size that is the smaller of: (1) the value specified by bufsiz or (2) the system parameter MAXBUF. If you do not specify bufsiz, the print symbiont uses the value of MAXBUF.

The print symbiont uses this size limit only for output operations. Output operations involve the placing of processed or formatted pages into a buffer that will be passed to the output routine.

The print symbiont uses the value specified by bufsiz only as an upper limit; most buffers that it writes will be smaller than this value.

worksiz

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Size in bytes of a work area to be allocated for the use of user routines. The worksiz argument is the address of a longword containing this size in bytes. If you do not specify worksiz, no work area is allocated.

A separate area of the specified size is allocated for each active symbiont stream.

maxqios

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the maximum number of outstanding $QIOs that a print symbiont stream using the LAT protocol may generate. Set symbiont process quotas large enough to handle the maximum number of QIOs multiplied by the number of streams, using a number between 2 and 32. For normal printing capabilities, the suggested quota is 10; for high-speed printing, use a larger number.

options

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Longword bit vector that specifies the LAT protocal option using the PSM$M_LAT_PROTOCOL symbolic value. Note that using the LAT_PROTOCOL option carries the following restrictions:

• Replacement of the output and job completion routines will be overridden
• Output device must be a LAT device

Description

The PSM$PRINT routine must be called exactly once after all user routines have been specified to the print symbiont. Each user routine is specified to the symbiont in a call to the PSM$REPLACE routine.

The PSM$PRINT routine allows you to specify whether the print symbiont is to be single-threaded or multithreaded, and if multithreaded, how many streams or threads it can have. In addition, this routine allows you to control the maximum size of the output buffer.

Condition Values Returned

SS$_NORMAL

Normal successful completion.

This routine also returns any condition values returned by the $SETPRV, $GETSYI, $PURGWS, and $DCLAST system services, as well as any condition values returned by the SMB$INITIALIZE routine documented in Chapter 18.

The PSM$READ_ITEM_DX routine obtains the value of message items that are sent by the job controller and stored by the symbiont.

Format

PSM$READ_ITEM_DX request_id ,item ,buffer

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.

Arguments

request_id

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Request identifier supplied by the symbiont to the user routine currently calling PSM$READ_ITEM_DX. The symbiont always supplies a request identifier when it calls a user routine with a service request. The request_id argument is the address of a longword containing this request identifier value.

Your user routine must copy the request identifier value that the symbiont supplies (in the request_id argument) when it calls your user routine. Then, when your user routine calls PSM$READ_ITEM_DX, it must supply (in the request_id argument) the address of the request identifier value that it copied.

item

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Item code that identifies the message item that PSM$READ_ITEM_DX is to return. The item argument is the address of a longword that specifies the item's code.

For a complete list and description of each item code, refer to the documentation of the item argument in the SMB$READ_MESSAGE_ITEM routine in Chapter 18.

buffer

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

Buffer into which PSM$READ_ITEM_DX returns the specified informational item. The buffer argument is the address of a descriptor pointing to this buffer.

The PSM$READ_ITEM_DX routine returns the specified informational item by copying that item to the buffer using one of the STR$COPY_xx routines documented in the OpenVMS RTL String Manipulation (STR$) Manual.

Description

The PSM$READ_ITEM_DX routine obtains the value of message items that are sent by the job controller and stored by the symbiont. Use PSM$READ_ITEM_DX to obtain information about the task currently being processed, for example, the name of the file being printed (SMBMSG$K_FILE_SPECIFICATION) or the name of the user who submitted the job (SMBMSG$K_USER_NAME).

Condition Values Returned

SS$_NORMAL	Normal successful completion.
PSM$_INVITMCOD	Invalid item code specified in the item argument.

This routine also returns any condition values returned by any of the STR$COPY_xx routines documented in the OpenVMS RTL String Manipulation (STR$) Manual.

The PSM$REPLACE routine substitutes a user service routine for a symbiont routine or adds a user service routine to the set of symbiont routines.

You must call PSM$REPLACE once for each routine that you replace or add.

Format

PSM$REPLACE code ,routine

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. The condition value that this routine can return is listed under Condition Value Returned.

Arguments

code

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Routine code that identifies the symbiont routine to be replaced by a user service routine. The code argument is the address of a longword containing the routine code.

Some routine codes identify routines that are supplied with the symbiont; when you specify such a routine code, you replace the symbiont-supplied routine with your service routine.

Two routine codes identify routines that are not supplied with the symbiont; when you specify such a routine code, your service routine is added to the set of symbiont routines.

Table 17-1 lists each routine code in the order in which it is called within the symbiont execution stream; this table also specifies whether a routine code identifies an input, formatting, or output routine and whether the routine is supplied with the symbiont.

Each programming language provides an appropriate mechanism for defining these routine codes. The following pages list each routine code in alphabetical order; the description of each code includes the following information about its corresponding routine:

• Whether the routine is supplied by the symbiont
• Whether the routine is an input, formatting, or output routine
• Under what conditions the routine is called
• What task the routine performs

Routine Codes

PSM$K_FILE_BURST

This code identifies a symbiont-supplied input routine; it is called whenever a file burst page is requested. This routine obtains information about the job, formats the file burst page, and returns the contents of the page to the input buffer. A file burst page follows a file flag page and precedes the contents of the file.

PSM$K_FILE_ERRORS

This code identifies a symbiont-supplied input routine; it is called when errors have occurred during the job. This routine places the error message text in the input buffer.

PSM$K_FILE_FLAG

This code identifies a symbiont-supplied input routine; it is called whenever a file flag page is requested. This routine obtains information about the job, formats the file flag page, and returns the contents of the page to the input buffer. A flag page follows the job burst page (if any) and precedes the file burst page (if any). It contains such information as the file specification of the file and the name of the user issuing the print request.

PSM$K_FILE_INFORMATION

This code identifies a symbiont-supplied input routine; it is called when the file information item has been specified by the job controller. This routine expands the file information item to text and returns it to the input buffer.

PSM$K_FILE_SETUP

This code identifies a symbiont-supplied input routine; it is always called. This routine queues any specified file-setup modules for insertion in the input stream when the PSM$K_FILE_SETUP routine closes.

PSM$K_FILE_SETUP_2

This code identifies a symbiont-supplied input routine; it is always called. This routine returns a form feed to ensure that printing of the file begins at the top of the page. This routine is called just before the main input routine.

PSM$K_FILE_TRAILER

This code identifies a symbiont-supplied input routine; it is called whenever a file trailer page is requested. This routine obtains information about the job, formats the file trailer page, and returns the contents of the page to the input buffer. A trailer page follows the last page of the file contents.

PSM$K_MAIN_FORMAT

This code identifies the symbiont-supplied formatting routine; it is always called. This routine performs numerous formatting functions. You cannot replace this routine.

PSM$K_FORM_SETUP

This code identifies a symbiont-supplied input routine; it is always called. This routine queues any specified form-setup modules for insertion in the input stream when the PSM$K_FORM_SETUP routine closes.

PSM$K_INPUT_FILTER

This code identifies a format routine that is not supplied by the symbiont. If the routine is supplied by the user, it is always called immediately prior to the symbiont-supplied formatting routine (routine code PSM$K_MAIN_FORMAT). An input-filter service routine is useful for modifying input data records and their carriage control before they are formatted by the symbiont.

PSM$K_JOB_BURST

This code identifies a symbiont-supplied input routine; it is called whenever a job burst page is requested. This routine obtains information about the job, formats the job burst page, and returns the contents of the page to the input buffer. A job burst page follows the job flag page and precedes the file flag page (if any) of the first file in the job. It is similar to a file burst page except that it appears only once per job and only at the beginning of the job.

PSM$K_JOB_COMPLETION

This code identifies a symbiont-supplied input routine that returns a form feed, which causes any output stored by the device to be printed. The routine is always called. It cannot be replaced when using the LAT protocol option.

PSM$K_JOB_FLAG

This code identifies a symbiont-supplied input routine; it is called whenever a job flag page is requested. This routine obtains information about the job, formats the job flag page, and returns the contents of the page to the input buffer. A job flag page is similar to a file flag page except that it appears only once per job, preceding the job burst page (if any).

PSM$K_JOB_RESET

This code identifies a symbiont-supplied input routine; it is always called. This routine queues any specified job-reset modules for insertion in the input stream when the PSM$K_JOB_RESET routine closes.

PSM$K_JOB_SETUP

This code identifies a symbiont-supplied input routine; it is always called. This routine checks to see if this is the first job to be printed on the device, and if so, it issues a form feed and then performs a job reset. See the description of the PSM$K_JOB_RESET routine for information about job reset.

PSM$K_JOB_TRAILER

This code identifies a symbiont-supplied input routine; it is called whenever a job trailer page is requested. This routine obtains information about the job, formats the job trailer page, and returns the contents of the page to the input buffer. A job trailer page is similar to a file trailer page except that it appears only once per job, as the last page in the job.

PSM$K_MAIN_INPUT

This code identifies a symbiont-supplied input routine; it is always called. This routine opens the file to be printed, returns input records to the input buffer, and closes the file.

PSM$K_LIBRARY_INPUT

This code identifies a symbiont-supplied input routine; it is called when an input routine closes and when modules have been requested for insertion in the input stream. This routine returns the contents of the specified modules, one record per call. You cannot replace this routine.

PSM$K_OUTPUT_FILTER

This code identifies a formatting routine that is not supplied by the symbiont. If the routine is supplied by the user, it is always called. This routine executes prior to the symbiont output routine (routine code PSM$K_OUTPUT). An output-filter service routine is useful for modifying output data buffers before they are passed to the output routine.

At the point where the output-filter routine executes within the symbiont execution stream, the input data is no longer in record format; instead, the data exists as a stream of characters. The carriage control, for example, is embedded in the data stream. Thus, the output buffer might contain what was once a complete record, part of a record, or several records.

PSM$K_PAGE_HEADER

This code identifies a symbiont-supplied input routine; it is called once at the beginning of each page if page headers are requested. This routine returns to the input buffer one or more lines containing information about the file being printed and the current page number. This routine is called only while the main input routine is open.

PSM$K_PAGE_SETUP

This code identifies a symbiont-supplied routine; it is called at the beginning of each page if page-setup modules were specified. This routine queues any specified page-setup modules for insertion in the input stream when the PSM$K_PAGE_SETUP routine closes. This routine is called only while the main input routine is open.

PSM$K_OUTPUT

This code identifies the symbiont-supplied output routine that writes the contents of the output buffer to the printing device, together with many other functions. This routine is always called. It cannot be replaced when using the LAT protocol option.

routine

Description

The PSM$REPLACE routine must be called each time a user service routine replaces a symbiont routine or is added to a set of symbiont routines.

The code argument specifies the symbiont routine to be replaced. The routine codes that can be specified in the code argument are of two types: those that identify existing print symbiont routines and those that do not. All the routine codes are similar, however, in the sense that each supplies a location within the print symbiont execution stream where your routine can execute.

By selecting a routine code that identifies an existing symbiont routine, you effectively disable that symbiont routine. The service routine that you specify might or might not perform the function that the disabled symbiont routine performs. If it does not, the net effect of the replacement is to eliminate that function from the list of functions performed by the print symbiont. Exactly what your service routine does is up to you.

By selecting a routine code that does not identify an existing symbiont routine (those that identify the input-filter and output-filter routines), your service routine has a chance to execute at the location signified by the routine code. Because the service routine you specify to execute at this location does not replace another symbiont routine, your service routine is an addition to the set of symbiont routines.

As mentioned, each routine code identifies a location in the symbiont execution stream, whether or not it identifies a symbiont routine. Table 17-1 lists each routine code in the order in which the location it identifies is reached within the symbiont execution stream.

Condition Value Returned

SS$_NORMAL

Normal successful completion.

The PSM$REPORT routine reports to the print symbiont the completion status of an asynchronous operation initiated by a user routine.

Such a user routine must return the completion status PSM$_PENDING. PSM$REPORT must be called exactly once for each time a user routine returns the status PSM$_PENDING.

Format

PSM$REPORT request_id [,status]

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. The condition value that this routine can return is listed under Condition Value Returned.

Arguments

request_id

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Request identifier supplied by the symbiont to the user routine at the time the symbiont called the user routine with the service request. The user routine must return the completion status PSM$_PENDING on the call for this service request. The request_id argument is the address of a longword containing the request identifier value.

The symbiont calls the user routine with a request code that specifies the function that the symbiont expects the user routine to perform. In the call, the symbiont also supplies a request identifier, which serves to identify the request. If the user routine initiates an asynchronous operation, a mechanism is required for notifying the symbiont that the asynchronous operation has completed and for providing the completion status of the operation.

The PSM$REPORT routine conveys the above two pieces of information. In addition, PSM$REPORT returns to the symbiont (in the request_id argument) the same request identifier value as that supplied by the symbiont to the user routine that initiated the operation. In this way, the symbiont synchronizes the completion status of an asynchronous operation with that invocation of the user routine that initiated the operation.

Any user routine that initiates an asynchronous operation must, therefore, copy the request identifier value that the symbiont supplies (in the request_id argument) when it calls the user routine. The user routine will later need to supply this value to PSM$REPORT.

In addition, when the user routine returns, which it does before the asynchronous operation has completed, the user routine must return the status PSM$_PENDING.

status

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Completion status of the asynchronous operation that has completed. The status argument is the address of a longword containing this completion status. The status argument is optional; if it is not specified, the symbiont assumes the completion status SS$_NORMAL.

The user routine that initiates the asynchronous operation must test for the completion of the operation and must supply the operation's completion status as the status argument to the PSM$REPORT routine. The Description section describes this procedure in greater detail.

If the completion status specified by status has the low bit clear, the symbiont aborts the task.

Description

An asynchronous operation is an operation that, once initiated, executes "off to the side" and need not be completed before other operations can begin to execute. Asynchronous operations are common in symbiont applications because a symbiont, if it is multithreaded, must handle concurrent I/O operations.

One example of a user routine that performs an asynchronous operation is an output routine that calls the $QIO system service to write a record to the printing device. When the user output routine completes execution, the I/O request queued by $QIO might not have completed. In order to synchronize this I/O request, that is, to associate the I/O request with the service request that initiated it, you should use the following mechanism:

1. In making the call to $QIO, specify the astadr and iosb arguments. The astadr argument specifies an AST routine to execute when the queued output request has completed, and the iosb argument specifies an I/O status block to receive the completion status of the I/O operation. Step 3 describes some functions that your AST routine will need to do.
2. Have the user output routine return the status PSM$_PENDING.
3. Write the AST routine to perform the following functions:
   1. Copy the completion status word from the I/O status block to a longword location that you will specify as the status argument in the call to PSM$REPORT.
   2. Call PSM$REPORT. Specify as the request_id argument the request identifier that was supplied by the print symbiont in the original call to the user output routine.

Condition Value Returned

SS$_NORMAL

Normal successful completion.