VMS Help PSM Routines, USER-INPUT-ROUTINE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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