Setup for IT Service Vision

Shared Appendix 8: Exits for the Process Task -- General Information

This appendix explains the exit points available during the process phase of IT Service Vision and guides you in selecting and coding exit points, if you want to use them.

Exits (sometimes referred to as exit points) are specific points, during the processing of data, at which control is transferred to a user-written routine, if a user-written routine is available. The process subsystem used by IT Service Vision allows for "exit" processing. What this means is that during the processing of raw data into the detail level of the PDB there are specific points where control is given to user-written code. Users often use exit points to filter or create data or to meet other custom requirements.

Process exits can be used to provide various types of functionality, for example:

to create additional datasets (such as accounting charges) on the same pass of the data.
to add various reporting capabilities in the midst of the process run.
for just about anything you've ever wanted to make process do!

Warnings and Disclaimers:

In any situation where you have the ability to affect and alter the intended flow and execution of code, there exists the possibility of error. As such, SAS Institute makes the following warnings and disclaimers with regard to the use of exits with IT Service Vision.

The example code shown in these "exit" files, while accurate, is subject to change. Any changes to this code that affect user exits will be reported to you via the normal usage notes packaged with maintenance.
There is simply no way that IT Service Vision can anticipate or be responsible for the processing that occurs within an exit. As such, exit code that you provide, if any, is simply included at the documented points. Any generation of reports during the actual execution of the exits is left up to you.
Additionally, it is possible to put code in exits that causes the data that will be stored in the IT Service Vision PDB to be invalid. SAS Institute cannot be responsible for invalid PDB data that is caused by user-written exits.

The bottom line is this: use exits with great caution.

Overview

Before getting mired down in the details of the individual exit points, let's first address some of the general "big picture" questions:

How do I tell IT Service Vision to use exits when running process?
Which exit points should I use?
How do I write my exits?
Are there any special variables available to my exits?
Are there any considerations that I need to be aware of?

We will explore each of these topics and then present more detailed information about the individual exit points.

How Do I Tell IT Service Vision to Use Exits when Running %CxPROCES?

An optional parameter, EXITSRC=, has been added to the %CxPROCES macros, where x is S for IT Service Vision for Open Systems, M for IT Service Vision for MVS, and W for IT Service Vision for PCs. The value to which EXITSRC= is set is the location of the exit-routine source code. The location can be either an external file/directory or the name of a SAS catalog.
If EXITSRC= is not specified on the %CxPROCES macro, then the process step is executed without regard to exit points.
If EXITSRC= is specified on the %CxPROCES macro, IT Service Vision first checks to see if the value specified is a valid external library (partitioned dataset for MVS; directory for Open Systems and PCs). If not, it then checks to see if the value specified is a SAS catalog.
If the value specified cannot be verified as either an external library or a SAS catalog, then the process macro terminates with an appropriate error message.
The interactive interface allows you to specify the EXITSRC= parameter as an Advanced feature of the Process/Reduce Wizard
on UNIX and PC, and on the Process Rawfiles screen of the MVS GUI..

Which Exit Points Should I Use?

This is not a simple question because the answer depends upon what you want to accomplish. The best way to determine the exit points to use is to consult the table that lists all of the exit points by name, includes a description of the locations in the supplied code, and includes the purpose that the exit point could serve.

You should then also look at the relevant code example (for the generic collector and for MVS data processed with SMF, or for Open Systems collectors and PC collectors) to make sure that you understand the context in which the exit point occurs, the purpose that you want to accomplish, and any implications that this may have on the regular processing of data into the PDB.

How Do I Write My Exits?

Exits exist as SAS source code, either in an external library member or as a .SOURCE member in a SAS catalog. The naming convention used is proc nnn, where nnn is the exit point number (with leading 0's). For a complete list of portable exit names and descriptive information, see below. The exits are numbered by 5's so that any future exit points that are added can still remain in numerical order.
Specific examples, based on the code for exit point proc005, are as follows:
- SAS Catalog
  Assume that the exits are stored in catalog SASUSER.CPEXITS. Then the source for the first exit point is in the member:
```
   SASUSER.CPEXITS.PROC005.SOURCE
```
  In this case, the value for EXITSRC= is SASUSER.CPEXITS.
- External Library
  Clearly this is a host-specific issue. IT Service Vision handles this in the following manner:
  
  MVS
  
  The exits must reside in a PDS. Assuming that the exits are stored in USERID.CPE.EXITS, then the location of the source code for the first exit point is USERID.CPE.EXITS(PROC005).
  In this case, the value for EXITSRC= is USERID.CPE.EXITS.
  
  Open Systems
  
  The exits must reside as flat files in a directory. The filename used for the IT Service Vision exit source should be entirely in lower case. Assuming that the exits are stored in /u/cpe/exits, then the location of the source code for the first exit point is /u/cpe/exits/proc005.sas.
  In this case, the value for EXITSRC= is /u/cpe/exits.
  
  PCs
  
  The exits must reside as flat files in a directory. The filename used for the IT Service Vision exit source should be entirely in lower case. Assuming that the exits are stored in c:\cpe\exits, then the location of the source code for the first exit point is c:/cpe/exits/proc005.sas.
Inside the process step, IT Service Vision verifies whether or not an exit exists in the location specified by EXITSRC=. If so, IT Service Vision includes the code for the exit when the process code is built in the preview buffer (and later submits the combined process code).
The actual code within an exit is nothing more than SAS language statements, as appropriate to the context in which the exit source code is included. Thus for some exits, the only valid contents may be data set options. For other exits, almost any valid SAS statement is valid. Again, each exit point needs to be taken in context to determine what is valid.
It cannot be over-emphasized that the exit routines are treated as source code that is located and included for each exit point. IT Service Vision does not keep track of any activity with regard to the actual execution (or non-execution) of the exit.
When the process step ends, a report is generated that lists the exit points that were included.
It is strongly recommended that each exit be coded as a macro and that the macro be given the same name as the exit point and then invoked. By doing so, it is easier to determine where any errors may have occurred (for example, if there is a syntax error in an exit). The following is a simple example of the recommended way to code the proc005 exit point:
```
   %macro proc005;
      /* actual exit-specific code goes here */
   %mend;
   %proc005
```
Do not place a semicolon after the invocation of the macro (in this example, the %proc005 that follows the %mend;).
If an exit needs to test the value of a macro variable (using %IF) or otherwise needs to be conditionally invoked, it is the responsibility of the exit to handle these matters. Again, the recommended way of doing this is to code the exit as a macro that has the same name as the exit point and then to invoke the macro immediately.
Here is an example that shows conditional invocation of the exit routine:
```
   %macro proc005;
      %if &SYSENV=BACK %then %do;
         /* actual exit-specific code goes here */
         %end;
   %mend;
   %proc005
```
Again, do not place a semicolon after the invocation of the macro (in this example, the %proc005 that follows the %mend;).

Are There Any Special Variables Available to My Exits?

The global macro variable CPTABLES is available to all of the exit points. The value of CPTABLES is a list of the names of all of the tables being processed in this invocation of the process macro. The table names are separated by white space.
CPARCTAB - a macro variable which contains a space-delimited list of all tables that are to be archived in the process run.
The global macro variable CPTABLE is available to each exit that occurs on a per-table or per-observation basis. The value of CPTABLE is the name of the table whose data are currently being processed.
CPARCTB - as each table is being processed, the CPARCTB macro variable is set to Y or N, depending upon whether or not this specific table is to be archived.
The global macro variable CPBYVAR is available to each exit that occurs on a per-table or per-observation basis. The value of CPBYVAR is the list of BY variables for the table whose data are currently being processed. The BY-variable names are separated by white space.
The global macro variable CPCUTDT is available to exit points proc150 through proc225. The value of CPCUTDT is the datetime constant used for the age limit trimming of the detail-level data set. That is, the value of CPCUTDT is the earliest date allowed for observations remaining in the detail-level data set.

Are There Any Considerations That I Need to Be Aware of?

If you want to delete observations in the final DATA step, it is recommended that you use exit point proc040. If you perform this activity at a later point (such as at exit point proc200), you run the risk of corrupting the data dictionary because accumulator values may have been incremented to include these (now deleted) observations.
Any macro variables that are created in an exit point will be LOCAL macro variables and will not be accessible to other exit points. If an exit needs to set a macro variable for use in a later exit point, then it is your responsibility to declare the macro variable as GLOBAL (by using a %GLOBAL macro statement).
The use of DATA step VIEWS by the generic SMF collector, as well as the use of proc135 for all platforms, in order to create a user-defined DATA step view, has several important implications:
- Whenever a DATA step view is defined, any additional data sets created in the same data step are not actually built until the view is executed. Therefore, exit points proc010 through proc085 are not actually executed until the view is executed. For the generic collector and MVS SMF collector, this means that the view is actually executed when the staged data is sorted.
- As a side effect of this, if you were to create an additional output data set using proc020 in the cases outlined previously, the data set would not exist at the time that exit point proc090 is encountered.
- For more information about working with DATA step views, see Chapter 14 of SAS Technical Report P-222, Changes and Enhancements to Base SAS Software Release 6.07.
The use of exit points proc035 and proc165 to add additional data sets for SET processing can have several subtle implications:
- For proc165, because the data sets in the SET statement are combined using the BY statement that follows, it is important that if you add any additional SET data sets, they should already be sorted using this BY-variables list. The BY list can be found in macro variable CPBYVAR.
- For proc165, counts of total observations, counts of observations with duplicate BY variables, counts of old observations, and counts of new observations, as well as the earliest and latest datetime values in the table, will be affected by the data in data sets that you may add to the SET statement. If you do not want the additional data sets to affect the counts, use the exit points preceding these specific points in processing, along with the IN= variables for the table and new (staged) data, to limit the scope to the desired input data sets.
- For proc035 and proc165, the data written to the table will include observations from all data sets in the SET statement. If you add additional data sets to the SET statement and do not want the additional data written to the table, use the exit point immediately before the OUTPUT statement to limit the scope to the desired input data sets.

Information about Specific Exit Points

The general flow of the generated code for process is as follows:

MACRO setup:: Macro variables are defined as global, and macro variable assignments are performed for the IT Service Vision macro variables shown at the beginning of the sample code.
DATA step:: To perform variable renames, to add variables SHIFT and HOUR, and to assign values to SHIFT, HOUR, and LSTPDATE. This could be referred to as the final staging of the data. For the MVS generic collector, the output is a SAS DATA step view.
PROC SORT:: The new (staged) data is sorted by using the BY variables for this table. Any duplicate observations are deleted.
PROC SORT:: If the detail-level data set is not sorted using the BY variables, then this PROC SORT step is built and executed in order to sort the detail-level data set by using the BY variables from the data dictionary.
DATA step:: To "merge" (actually SET-BY) the new data and the detail-level data. This updates the detail level of the PDB.