User routines are called by the PCA collector during system
    service interception. They provide the user with the following
    capabilities:

    o  Independent recording (including system service information);

    o  Control of the recording by PCA of system services;

1  –  API

    The PCA Collector supports the following application program
    interface to user routines.

    pca-control-flag =
       entry-routine(
          ap-pointer,
          sequence-number,
          CPU-time,
          system-service-name-pointer,
          system-service-name-index,
          user-routine-buffer-pointer)

    pca-control-flag =
       exit-routine(
          ap-pointer,
          sequence-number,
          CPU-time,
          system-service-name-pointer,
          system-service-index,
          user-routine-buffer-pointer)

    Routine Parameter           Description

    pca-control-flag            Flag to indicate whether PCA is to
                                attempt to write the system service
                                record. The write will only be
                                attempted if the low bit is set.
    ap-pointer                  The contents of the argument pointer
                                at the system service call by value.
    sequence-number             The PCA sequence number corresponding
                                to the performance data record by
                                value.
    CPU-time                    The CPU time by value.
    system-service-name-        The name of the system service being
    pointer                     called by the address of a counted
                                ASCII string.
    system-service-index        The index of the system service being
                                called by value.
    user-routine-buffer-        User specified buffer by reference.
    pointer

    The following rule applies regarding the construction of user
    routines images:

    1. The user must write a shareable image, making the entry and
       exit routine names UNIVERSAL;

2  –  Example

    The DEMO_USER_ROUTINE example is intended to introduce the
    concept of User Routines. The example files are:

    PCA$EXAMPLES:*DEMO_USER_ROUTINE*.*

2.1  –  Construction

    The example user routine image can be constructed by running:

  $ @PCA$EXAMPLES:DEMO_USER_ROUTINE.COM

    If you are using the VAX C rather than DEC C compiler replace the
    line:

        SYS$LIBRARY:DECCRTL.OLB/LIBRARY
                    ^^^

    from VAX_DEMO_USER_ROUTINE.OPT with:

        SYS$LIBRARY:VAXCRTL.OLB/LIBRARY
                    ^^^

2.2  –  Usage

    Run an example program to check user routine support:

  $ DEFINE DEMO_USER_ROUTINE DISKN:[USER]DEMO_USER_ROUTINE.EXE

    You must define the logical name to access the user routine image
    if it is not found in SYS$SHARE.

  $ DEFINE LIB$DEBUG PCA$COLLECTOR
  $ RUN PCA$EXAMPLES:PCA$8QUEENS.EXE
  PCAC> SET SERVICES/USER_ROUTINE=(DEMO_USER_ROUTINE,-)
  _PCAC> DEMO_ENTRY$USER_ROUTINE,-
  _PCAC> DEMO_EXIT$USER_ROUTINE
  PCAC> GO

    Using LIB$DEBUG is the preferred method for using the PCA
    collector.

3  –  Usage

    For information on specifying collection with user routines enter
    the following commands:

  $ PCA
  PCAA> HELP SET SERVICES /NOUSER_ROUTINE
  PCAA> HELP SET SERVICES /USER_ROUTINE
  PCAA> HELP SET IO_SERVICES /NOUSER_ROUTINE
  PCAA> HELP SET IO_SERVICES /USER_ROUTINE

3.1  –  Restrictions

    -  PCA will not call, or invoke, your user routine image if it is
       linked with warnings or errors.

    -  You must define a logical name to access the user routine
       image if it is not found in SYS$SHARE.

    -  A system service routine which is invoked from a user-
       supplied routine should be written in the C language (as
       referenced by the /USER_ROUTINE qualifier in the glossary
       of the DIGITAL Performance and Coverage Analyzer for OpenVMS
       Reference Manual). If written in some other languages, it may
       have the effect of locking up PCA. Examples are provided in
       PCA$EXAMPLES.

3.2  –  Side Effects

    Lost Data Indications will occur in the PCA Analyzer if the user
    supplied routines instructs PCA not to write some data records;