1  User_Routines
   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;
 

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

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

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

2  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  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  Side_Effects
   Lost Data Indications will occur in the PCA Analyzer if the user
   supplied routines instructs PCA not to write some data records;