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

    The PSM$REPLACE routine substitutes a user service routine for
    a symbiont routine or adds a user service routine to the set of
    symbiont routines.

    You must call PSM$REPLACE once for each routine that you replace
    or add.

    Format

      PSM$REPLACE  code ,routine

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. The condition value that this routine
    can return is listed under Condition Value Returned.

2 - Arguments

 code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Routine code that identifies the symbiont routine to be replaced
    by a user service routine. The code argument is the address of a
    longword containing the routine code.

    Some routine codes identify routines that are supplied with the
    symbiont; when you specify such a routine code, you replace the
    symbiont-supplied routine with your service routine.

    Two routine codes identify routines that are not supplied with
    the symbiont; when you specify such a routine code, your service
    routine is added to the set of symbiont routines.

    Each programming language provides an appropriate mechanism for
    defining these routine codes. The following pages list each
    routine code in alphabetical order; the description of each
    code includes the following information about its corresponding
    routine:

    o  Whether the routine is supplied by the symbiont

    o  Whether the routine is an input, formatting, or output routine

    o  Under what conditions the routine is called

    o  What task the routine performs

3 - Routine Codes

 PSM$K_FILE_BURST

    This code identifies a symbiont-supplied input routine; it is
    called whenever a file burst page is requested. This routine
    obtains information about the job, formats the file burst page,
    and returns the contents of the page to the input buffer. A file
    burst page follows a file flag page and precedes the contents of
    the file.

 PSM$K_FILE_ERRORS

    This code identifies a symbiont-supplied input routine; it is
    called when errors have occurred during the job. This routine
    places the error message text in the input buffer.

 PSM$K_FILE_FLAG

    This code identifies a symbiont-supplied input routine; it is
    called whenever a file flag page is requested. This routine
    obtains information about the job, formats the file flag page,
    and returns the contents of the page to the input buffer. A flag
    page follows the job burst page (if any) and precedes the file
    burst page (if any). It contains such information as the file
    specification of the file and the name of the user issuing the
    print request.

 PSM$K_FILE_INFORMATION

    This code identifies a symbiont-supplied input routine; it is
    called when the file information item has been specified by the
    job controller. This routine expands the file information item to
    text and returns it to the input buffer.

 PSM$K_FILE_SETUP

    This code identifies a symbiont-supplied input routine; it is
    always called. This routine queues any specified file-setup
    modules for insertion in the input stream when the PSM$K_FILE_
    SETUP routine closes.

 PSM$K_FILE_SETUP_2

    This code identifies a symbiont-supplied input routine; it is
    always called. This routine returns a form feed to ensure that
    printing of the file begins at the top of the page. This routine
    is called just before the main input routine.

 PSM$K_FILE_TRAILER

    This code identifies a symbiont-supplied input routine; it is
    called whenever a file trailer page is requested. This routine
    obtains information about the job, formats the file trailer
    page, and returns the contents of the page to the input buffer. A
    trailer page follows the last page of the file contents.

 PSM$K_MAIN_FORMAT

    This code identifies the symbiont-supplied formatting routine;
    it is always called. This routine performs numerous formatting
    functions. You cannot replace this routine.

 PSM$K_FORM_SETUP

    This code identifies a symbiont-supplied input routine; it is
    always called. This routine queues any specified form-setup
    modules for insertion in the input stream when the PSM$K_FORM_
    SETUP routine closes.

 PSM$K_INPUT_FILTER

    This code identifies a format routine that is not supplied by the
    symbiont. If the routine is supplied by the user, it is always
    called immediately prior to the symbiont-supplied formatting
    routine (routine code PSM$K_MAIN_FORMAT). An input-filter service
    routine is useful for modifying input data records and their
    carriage control before they are formatted by the symbiont.

 PSM$K_JOB_BURST

    This code identifies a symbiont-supplied input routine; it is
    called whenever a job burst page is requested. This routine
    obtains information about the job, formats the job burst page,
    and returns the contents of the page to the input buffer. A job
    burst page follows the job flag page and precedes the file flag
    page (if any) of the first file in the job. It is similar to a
    file burst page except that it appears only once per job and only
    at the beginning of the job.

 PSM$K_JOB_COMPLETION

    This code identifies a symbiont-supplied input routine that
    returns a form feed, which causes any output stored by the
    device to be printed. The routine is always called. It cannot
    be replaced when using the LAT protocol option.

 PSM$K_JOB_FLAG

    This code identifies a symbiont-supplied input routine; it is
    called whenever a job flag page is requested. This routine
    obtains information about the job, formats the job flag page,
    and returns the contents of the page to the input buffer. A job
    flag page is similar to a file flag page except that it appears
    only once per job, preceding the job burst page (if any).

 PSM$K_JOB_RESET

    This code identifies a symbiont-supplied input routine; it is
    always called. This routine queues any specified job-reset
    modules for insertion in the input stream when the PSM$K_JOB_
    RESET routine closes.

 PSM$K_JOB_SETUP

    This code identifies a symbiont-supplied input routine; it is
    always called. This routine checks to see if this is the first
    job to be printed on the device, and if so, it issues a form feed
    and then performs a job reset. See the description of the PSM$K_
    JOB_RESET routine for information about job reset.

 PSM$K_JOB_TRAILER

    This code identifies a symbiont-supplied input routine; it is
    called whenever a job trailer page is requested. This routine
    obtains information about the job, formats the job trailer page,
    and returns the contents of the page to the input buffer. A job
    trailer page is similar to a file trailer page except that it
    appears only once per job, as the last page in the job.

 PSM$K_MAIN_INPUT

    This code identifies a symbiont-supplied input routine; it is
    always called. This routine opens the file to be printed, returns
    input records to the input buffer, and closes the file.

 PSM$K_LIBRARY_INPUT

    This code identifies a symbiont-supplied input routine; it is
    called when an input routine closes and when modules have been
    requested for insertion in the input stream. This routine returns
    the contents of the specified modules, one record per call. You
    cannot replace this routine.

 PSM$K_OUTPUT_FILTER

    This code identifies a formatting routine that is not supplied
    by the symbiont. If the routine is supplied by the user, it is
    always called. This routine executes prior to the symbiont output
    routine (routine code PSM$K_OUTPUT). An output-filter service
    routine is useful for modifying output data buffers before they
    are passed to the output routine.

    At the point where the output-filter routine executes within the
    symbiont execution stream, the input data is no longer in record
    format; instead, the data exists as a stream of characters. The
    carriage control, for example, is embedded in the data stream.
    Thus, the output buffer might contain what was once a complete
    record, part of a record, or several records.

 PSM$K_PAGE_HEADER

    This code identifies a symbiont-supplied input routine; it is
    called once at the beginning of each page if page headers are
    requested. This routine returns to the input buffer one or more
    lines containing information about the file being printed and the
    current page number. This routine is called only while the main
    input routine is open.

 PSM$K_PAGE_SETUP

    This code identifies a symbiont-supplied routine; it is called at
    the beginning of each page if page-setup modules were specified.
    This routine queues any specified page-setup modules for
    insertion in the input stream when the PSM$K_PAGE_SETUP routine
    closes. This routine is called only while the main input routine
    is open.

 PSM$K_OUTPUT

    This code identifies the symbiont-supplied output routine that
    writes the contents of the output buffer to the printing device,
    together with many other functions. This routine is always
    called. It cannot be replaced when using the LAT protocol option.

 routine

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    User service routine that is to replace a symbiont routine or
    to be included. The routine argument is the address of the user
    routine entry point.

4 - Description

    The PSM$REPLACE routine must be called each time a user service
    routine replaces a symbiont routine or is added to a set of
    symbiont routines.

    The code argument specifies the symbiont routine to be replaced.
    The routine codes that can be specified in the code argument
    are of two types: those that identify existing print symbiont
    routines and those that do not. All the routine codes are
    similar, however, in the sense that each supplies a location
    within the print symbiont execution stream where your routine can
    execute.

    By selecting a routine code that identifies an existing symbiont
    routine, you effectively disable that symbiont routine. The
    service routine that you specify might or might not perform
    the function that the disabled symbiont routine performs. If
    it does not, the net effect of the replacement is to eliminate
    that function from the list of functions performed by the print
    symbiont. Exactly what your service routine does is up to you.

    By selecting a routine code that does not identify an existing
    symbiont routine (those that identify the input-filter and
    output-filter routines), your service routine has a chance to
    execute at the location signified by the routine code. Because
    the service routine you specify to execute at this location does
    not replace another symbiont routine, your service routine is an
    addition to the set of symbiont routines.

    As mentioned, each routine code identifies a location in the
    symbiont execution stream, whether or not it identifies a
    symbiont routine.

5 - Condition Value Returned

    SS$_NORMAL         Normal successful completion.