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

    The user-written USER-OUTPUT-ROUTINE performs output operations.
    You supply a user output routine by calling the PSM$REPLACE
    routine with the routine code PSM$K_OUTPUT.

    Format

      USER-OUTPUT-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 output routine. The request_id argument is the address of a
    longword containing this value.

    If your output routine initiates an asynchronous operation (for
    example, a call to the $QIO system service), you must save the
    request_id argument because you will need to store the request
    identifier value for later use with 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 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 supplied by the symbiont when it calls your
    output routine. The func argument is the address of a longword
    containing this code.

    The function code specifies the reason the symbiont is calling
    your output 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 via the funcdesc and funcarg arguments. The
    description of each output function code, therefore, includes a
    description of how these two arguments are used for that function
    code.

    The following list describes all the function codes that the
    symbiont might supply when it calls your output routine (function
    codes applicable only to input and formatting routines are
    explained in the descriptions of the user input routine and user
    formatting routine, respectively). Each programming language
    provides an appropriate mechanism for defining these function
    codes.

3 - Function Codes for Output Routines

 PSM$K_OPEN

    When the symbiont calls your output routine with this function
    code, your routine should prepare to move data to the device
    by performing such tasks as allocating the device, assigning a
    channel to the device, and so on. The next time the symbiont
    calls your output routine, the symbiont specifies one of the
    WRITE function codes (PSM$K_WRITE or PSM$K_WRITE_NOFORMAT).

    The symbiont calls your output routine with the PSM$K_OPEN
    function code when the symbiont receives the SMBMSG$K_START_
    STREAM message from the job controller.

    If your output routine returns an error condition value (low
    bit clear) to the PSM$K_OPEN function call, the job controller
    stops processing on the stream and reports the error to whomever
    entered the DCL command START/QUEUE.

    The funcdesc argument is the address of a descriptor that
    identifies the name of the device to which the output routine
    is to write. This device name is established by the DCL command
    INITIALIZE/QUEUE/ON=device.

    The funcarg argument is the address of a longword into which
    the user output routine returns the device status longword.
    Your output routine sets bits in the device status longword to
    indicate to the job controller whether the device falls into one
    of the following categories:

    o  Can print lowercase letters

    o  Is a terminal

    o  Is connected to the CPU by means of a modem (remote)

    If your output routine does not set any of these bits in the
    device status longword, the job controller assumes, by default,
    that the device is a line printer that prints only uppercase
    letters.

 PSM$K_WRITE

    When the symbiont calls your routine with this function code,
    your routine must write data to the device. The symbiont
    supplies the data to be written in the funcdesc argument. Compaq
    recommends that you use one of the Run-Time Library string
    routines to access the data in the buffer described by the
    funcdesc argument.

 PSM$K_WRITE_NOFORMAT

    When the symbiont calls your routine with this function code,
    your routine must write data to the device and must indicate to
    the device driver that the data is not to be formatted.

    The symbiont calls your routine with this function code when:
    (1)  the print request specifies the PASSALL option or (2) data
    is introduced by the ANSI DCS (device control string) escape
    sequence.

    The symbiont supplies the data to be written in the funcdesc
    argument. Compaq recommends that you use one of the Run-Time
    Library string routines to move the data from the descriptor to
    the device.

    The output routine of the symbiont informs the device driver not
    to format the data in the following way:

    o  When the device is a line printer, the symbiont's output
       routine specifies the IO$_WRITEPBLK function code when it
       calls the $QIO system service.

    o  When the device is a terminal, the symbiont's output routine
       specifies the IO$M_NOFORMAT function modifier when it calls
       the $QIO system serivce.

 PSM$K_CANCEL

    When the symbiont calls your routine with this function code,
    your routine must abort any outstanding asynchronous I/O
    requests.

    The output routine supplied by the symbiont aborts outstanding
    I/O requests by calling the $CANCEL system service with the IO$_
    CANCEL function code.

    If your output routine returned the condition value PSM$_
    PENDING to one or more previous write requests that are still
    outstanding (that is, PSM$REPORT has not yet been called to
    report completion), then your output routine must call PSM$REPORT
    one time for each outstanding write request that is canceled with
    this call. That is, canceling an asynchronous write request does
    not relieve the user output routine of the requirement to call
    PSM$REPORT once for each asynchronous write request.

    You cannot use the funcdesc and funcarg arguments with this
    function code.

 PSM$K_CLOSE

    When the symbiont calls your routine with this function code,
    your output routine must terminate processing and release any
    resources it allocated (for example, channels assigned to the
    device).

    You cannot use the funcdesc and funcarg arguments with this
    function code.

 Other Output Function Codes

    The symbiont can call your output 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 output 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 output 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:user_arg
    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.

    The contents of the function argument can vary for each function.
    Refer to the description of each function code to determine the
    contents of the function argument. In some cases, the function
    argument is not used.

4 - Condition Values Returned

    SS$_NORMAL         Normal successful completion. The user output
                       routine has completed the function that the
                       symbiont requested.
    PSM$_FUNNOTSUP     Function not supported. The user output
                       routine does not support or does not recognize
                       the function code supplied by the symbiont.
                       To ensure future compatibility, your output
                       routine should return this status for any
                       unrecognized status codes.
    PSM$_PENDING       Requested function accepted but not completed.
                       Your output routine can return this status
                       only with PSM$K_WRITE and PSM$K_WRITE_NOFORMAT
                       function calls. Further, if your routine
                       returns PSM$_PENDING, your routine must
                       eventually signal completion by way of the
                       PSM$REPORT routine. Refer to the description
                       of the PSM$REPORT routine for more information
                       about asynchronous write operations and the
                       PSM$_PENDING condition value.

    This routine also returns any error condition values that you
    have coded your output routine to return.