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
1 – 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.
2 – 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.
4 – 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.