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