Copyright Digital Equipment Corp. All rights reserved.
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.