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

    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

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 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 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 for more information.

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

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