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