OpenVMS Utility Routines Manual
USER-FORMAT-ROUTINE
The user-written USER-FORMAT-ROUTINE performs format operations. The
symbiont's control logic routine calls your format routine at one of
two possible points within the symbiont's execution stream. You select
this point by specifying one of two routine codes when you call the
PSM$REPLACE routine.
A user format routine can be an input filter routine (routine code
PSM$K_INPUT_FILTER) or an output filter routine (routine code
PSM$K_OUTPUT_FILTER). The main format routine (routine code
PSM$K_MAIN_FORMAT) cannot be replaced.
A user format routine must use the call interface described here.
Format
USER-FORMAT-ROUTINE request_id ,work_area ,func ,func_desc_1
,func_arg_1 ,func_desc_2 ,func_arg_2
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 when it calls your format
routine. The request_id argument is the address of a
longword containing this request identifier value.
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 specifying the service that the symbiont expects your
format routine to perform. The func argument is the
address of a longword into which the symbiont writes this function code.
The function code specifies the reason the symbiont is calling your
format routine or, in other words, the service that the symbiont
expects your routine to perform at this time.
The PSM$K_FORMAT function code is the only one to which your format
routine must respond. When the symbiont calls your format routine with
this function code, your routine must move a record from the input
buffer to the output buffer.
The symbiont can call your format 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 format
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, which are discussed
in more detail in Section 17.3.5, 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 format 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.
func_desc_1
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Descriptor supplying an input record to be processed by the format
routine. The func_desc_1 argument is the address of a
string descriptor. By using this argument, the symbiont supplies the
input record that your format routine is to process. Because this
descriptor can be of any valid string type, your format routine should
use the Run-Time Library string routines to analyze this descriptor and
to manipulate the input record.
func_arg_1
| OpenVMS usage: |
vector_byte_unsigned |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Carriage control for the input record supplied by
func_desc_1. The func_arg_1 argument
is the address of a 4-byte vector that specifies the carriage control
for the input record. The following diagram depicts the format of this
4-byte vector:
Bytes 0 and 1 describe the leading carriage control to apply to the
input data record; bytes 2 and 3 describe the trailing carriage control.
Byte 0 is a number specifying the number of times the carriage control
specifier in byte 1 is to be repeated preceding the input data record.
Byte 2 is a number specifying the number of times the carriage control
specifier in byte 3 is to be repeated following the input data record.
For values of the carriage control specifier from 1 to 255, the
specifier is the ASCII character to be used as carriage control. Value
0 represents the ASCII "newline" sequence. Newline
consists of a carriage return followed by a linefeed.
The func_arg_1 argument is not used if your format
routine is an output filter routine (routine code PSM$K_OUTPUT_FILTER).
See the Description section for more information.
func_desc_2
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by reference |
Descriptor of a buffer to which your format routine writes the
formatted output record. The func_desc_2 argument is
the address of a string descriptor.
Your format routine must return the formatted data record by using the
func_desc_2 argument.
Your format routine should use the Run-Time Library string routines to
write into the buffer specified by this descriptor.
func_arg_2
| OpenVMS usage: |
vector_byte_unsigned |
| type: |
byte (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Carriage control for the output record returned in
func_desc_2. The func_arg_2 argument
is the address of a 4-byte vector that specifies the carriage control
for the output record. See the description of
func_arg_1 for the contents and format of this 4-byte
vector.
If you do not process the carriage-control information supplied in
func_arg_1, then you should copy that value into
func_arg_2. Otherwise, the carriage-control
information will be lost.
The func_arg_2 argument is not used if your format
routine is an output filter routine (routine code PSM$K_OUTPUT_FILTER).
See the Description section help topic for more information.
Description
When used, the func_arg_1 argument describes
carriage-control information for the input data record, and the
func_arg_2 argument describes carriage-control
information for the output data record.
The input data record is passed to the format routine (input filter or
output filter) for processing, and the output data record is returned
by the format routine (input filter or output filter).
One of the tasks performed by the main format routine (routine code
PSM$K_MAIN_FORMAT) is that of embedding the carriage-control
information (specified by func_arg_1) into the data
record (specified by func_desc_1). Thus, the output
data (specified by func_desc_2) contains embedded
carriage control and is thus no longer in record format; it is,
therefore, properly referred to as an output data stream rather than an
output data record.
Similarly, the output filter routine (routine code
PSM$K_OUTPUT_FILTER), which executes after the main format routine,
uses neither the func_arg_1 nor
func_arg_2 argument; the data it receives (via
func_desc_1) and the data it returns (via
func_desc_2) are data streams, not data records.
However, the input filter routine (routine code PSM$K_INPUT_FILTER),
which executes before the main format routine, uses both
func_arg_1 and func_arg_2. This is so
because the main format routine has not yet executed, and so the
carriage control information has not yet been embedded in the data
record.
Condition Values Returned
|
SS$_NORMAL
|
Successful completion. The user format routine has completed the
function that the symbiont requested.
|
|
PSM$_FUNNOTSUP
|
Function not supported. The user format routine does not support or
does not recognize the function code supplied by the symbiont. To
ensure future compatibility, your format routine should return this
status for any unrecognized status codes.
|
This routine also returns any error condition values that you have
coded your format routine to return. Refer to Section 17.3.1 for more
information about error condition values.
USER-INPUT-ROUTINE
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
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 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.
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. Compaq 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
|
Implied carriage control. For this type, the 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
|
Fortran carriage control. For this type, the 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_INTERNAL
|
Embedded carriage control. For this type, the 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. Compaq 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, which are discussed
in detail in Section 17.3.5, 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.
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.
|
|
