The TRACER Procedure Seeing how they run
From "VS Procedure",  Access 87, January 1987
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

Most programming languages provide a means of observing the logical flow of a program while it is running. In Procedure Language, this ability is provided by the TRACE facility. This month we'll look at the trace options available to the procedure writer and how to use them.

Why Trace?

TRACE shows you the exact path the procedure took in actual operation by collecting selected information at run time and creating a report of that information. Using TRACE, you can see the steps performed, the value changes of procedure variables, the completion status of all steps, and the resource usage in CPU or actual time. The level of detail this listing contains can be controlled by selecting or suppressing any of these options.

Of course, the most common use for TRACE is while debugging a new procedure. Other reasons might include production job logging, completion status reporting, or analysis of computer resource usage.

There are three ways to use TRACE: through the Wang Editor (the most common point of access); through statements permanently coded in the procedure; or by using the PROC program. Let's examine all three.

TRACE options in the Editor

If you are new to TRACE, try it from the Editor first. To do this, call the procedure into the Editor and press PF(02) from the Special Menu to enter the SET parameters. Notice that PF(04) allows you to "Change Tracing Options." From the TRACING menu you have the following options:

• TRACE (Y/N): this turns the tracing facility on or off.

• RUNONLY: if set to NO, all statements in the procedure will appear on the trace listing; if set to YES, only RUN statements will appear.

• VARIABLE: if set to YES, the contents of all variables will be listed.

• RESOURCE: if set to YES, the elapsed time and CPU time will appear.

• START/END: controls which areas of the procedure will be traced; accepts the range of line numbers.

The listing that is produced during this trace will be the same name as the procedure itself and located in your default spooling library. The Editor will provide a new PF key to display this listing each time you return from a run. Try each of the trace options from the Editor and note their effects on the listing.

Using TRACE from the Procedure itself

Another way to invoke a trace listing is to code it into the procedure. The advantages of this approach are that you can specify the listing's file name and location, scratch any previous copies, and easily control the area to be traced. One possible disadvantage is that will produce a trace listing with every run of the procedure.

The starting and ending lines of the trace specification might look like this:

S00: TRACE [ INTO &TRACEFIL IN &TRACELIB ON &TRACEVOL ], RESOURCES = YES, [ default = NO ] SCRATCH = YES, [ default = NO ] STATEMENTS = RUN, [ default = ALL ] VARIABLES = YES [ default = NO ] [ . . . code to be traced . . . ] S99: TRACE END

As you can see, there are several parameters you can control. Any of these statements can be left out and the default values take effect.

Using the PROC interpreter

The third method of tracing a procedure is to run the PROC program in the system library. PROC is a means of directly accessing the procedure interpreter, the syntax checker, and the TRACE facility. From this point, you can run the procedure, enter the Editor produce a trace listing, check syntax, or display the procedure.

PROC is located in the system library (@SYSTEM@) on the system volume. The first screen to appears is the OPTIONS screen (see Figure 1). To run with the TRACE option, enter the name of the procedure and press PF(09). The TRACE screen will appear (see Figure 2), showing trace options that are similar to those in the Editor. After entering your selections press (RETURN) and the procedure will begin as normal. At the conclusion of the procedure, the OPTIONS menu reappears with the trace listing just created. As with the Editor, the trace listing will be located in the default spool library, named the same as the procedure itself.

The TRACER procedure

This month's procedure automates the TRACE function on existing procedures by prompting for a procedure name and passing that name to PROC. I have set the defaults to produce a listing suitable to discern the machine requirements of the run - i.e., only RUN statements and machine resource usage is logged. Of course, any other settings are possible.

Figure 3 shows the procedure. Step S01 accepts the procedure name, verifies that it exists, and checks whether a PF key or the (RETURN) key has been pressed. Control then passes to the appropriate sections to run PROC, DISPRINT, or to exit from the procedure. After successful conclusion control returns to the PROMPT screen.

Note the use of the &BYTE function to assign non-displayable characters to &BLINKFAC and &BRITEFAC. Those of you who work with COBOL, BASIC, or RPG II will recognize this as Field Attribute Characters (FACs). FACs control how a field is displayed and whether it can be modified. When positioned immediately in front of an item, they control display attributes such as blinking, brightness, and whether modifications are allowed to the field. I use them here to control the blinking of the message field. (I'll have further uses for FACs in future columns.)

I use this procedure to check the resource usage and return status of procedures that I cannot modify due to their protection. The same process could be used to provide a crude run log of all procedures run, perhaps for user billing or cost allocation by department.

Up and running

Next month I'll cover the use of subroutines in Procedure.

Figure 1: The Procedure OPTIONS Screen

Wang VS GETPARM v 7 Parameter Reference Name: OPTIONS Message Id: 0001 Component: PROC Information Required by DSBLOG Active Subprogram is PROC VS Procedure Language Interpreter ver 07.53.01 in @SYSTEM@ on SYSTEM Enter the procedure information and select: FILE = ******** in LIBRARY = VSAIDS** on VOLUME = SYSTEM (1) Run - Run procedure or program (2) Edit - Run Editor To edit file (9) Trace - Run procedure and trace execution (10) Check - Check procedure for correct syntax (14) Display - Display file (16) Exit - End processing

Figure 2: The Procedure TRACE Screen

Wang VS GETPARM v 7 Parameter Reference Name: TRACE Message Id: 0002 Component: PROC Information Required by DSBLOG Active Subprogram is PROC VS Procedure Language Interpreter ver 07.53.01 in @SYSTEM@ on SYSTEM Specify trace options and press (ENTER): Trace Run statements only? RUNONLY = NO* (YES/NO) Trace values of variables? VARIABLE = NO* (YES/NO) Trace resource usage? RESOURCE = NO* (YES/NO) Trace within line range: START = ALL*** END = ****** (ENTER) Accept - Accept options and begin trace (1) Return - Return to OPTIONS screen (16) Exit - End processing

Figure 3: The TRACER Procedure

PROCEDURE TRACER - Run-time procedure trace facility ********************************************************************** * * TRACER - run-time program & procedure monitor * * This procedure is a variation of TRACER, which was featured in * the January 1987 ACCESS 87. It produces a trace listing from * all procedures and object files. * * For further discussion of the Procedure TRACE option, see Wang's * Procedure Language Reference, publication 800-1205-05. * * Written by Dennis S. Barnes * * MODIFICATION HISTORY * * Initial version: 10/27/86 - Dennis S. Barnes * * Version 1.01 10/28/86 * Uses $VERIFY to check file name. * * Version 1.02 10/30/86 * Uses direct procedure TRACE function instead * ********************************************************************** * &MESSAGE Declared GLOBAL to receive message data from $VERIFY ****** DECLARE &MESSAGE GLOBAL STRING (71) DECLARE &INFIL, &INLIB STRING (08) DECLARE &TRFIL, &TRLIB STRING (08) DECLARE &INVOL, &TRVOL STRING (06) DECLARE &ID STRING (03) DECLARE &OPTSCR STRING (03) INITIAL "NO " DECLARE &OPTVAR STRING (03) INITIAL "NO " DECLARE &MODE INTEGER INITIAL 0 DECLARE &FILETYPE STRING (01) DECLARE &RUNSTEP STRING (03) INITIAL "@ " DECLARE &ALARM STRING (03) DECLARE &RC INTEGER DECLARE &BLINKFAC, &BRITEFAC STRING (01) EXTRACT &TRLIB = SPOOLIB, &TRVOL = SPOOLVOL * Field Attribute Characters (FAC's) follow ************************** ASSIGN &BRITEFAC = &BYTE(132) [ Equivalent to 84 HEX ] ASSIGN &BLINKFAC = &BYTE(148) [ " " 94 " ] ASSIGN &MESSAGE = &BRITEFAC !! "Please enter parameters and press (RETURN)" * Main logic follows ************************************************* S00: ASSIGN &INFIL = " " [ Initialize input file name ] ASSIGN &TRFIL = " " [ Initialize trace file name ] ASSIGN &ALARM = "NO " S01: PROMPT PFKEY = &RUNSTEP (2,2), ALARM = &ALARM CENTER BRIGHT LINE " "; CENTER BRIGHT LINE "Run & trace facility - Version 1.02";; CENTER "Please enter the name of the procedure to be traced:";; CENTER "RUN FILE =", UPPER &INFIL, " IN ", UPPER &INLIB, " ON ", UPPER &INVOL;; CENTER "and the options and location for the trace listing:";; CENTER "OUTPUT LISTING =", UPPER &TRFIL, " IN ", UPPER &TRLIB, " ON ", UPPER &TRVOL; CENTER "SCRATCH TRACE LISTING =", UPPER &OPTSCR, " [ YES, NO ]";; CENTER "Press PF(14) to display files (DISPMANY)"; CENTER "Press PF(16) to exit ";; CENTER &MESSAGE(1,*) IF &LABEL(&RUNSTEP) GOTO &RUNSTEP ASSIGN &ALARM = "YES" ASSIGN &MESSAGE = &BLINKFAC !! "Invalid key pressed - please try again" GOTO S01 * Verify input file name ********************************************* @0: RUN $VERIFY [ in library on volume ] USING &INFIL, &INLIB, &INVOL IF &MESSAGE = " " GOTO S03 ASSIGN &ALARM = "YES" GOTO S01 * Verify existence of file ******************************************* S03: IF EXISTS FILE &INFIL IN &INLIB ON &INVOL GOTO S04 ASSIGN &ALARM = "YES" ASSIGN &MESSAGE = &BLINKFAC !! "File does not exist - please re-enter" GOTO S01 * Verify output file ************************************************* S04: IF &TRFIL = " " ASSIGN &TRFIL = &INFIL RUN $VERIFY [ in library on volume ] USING &TRFIL, &TRLIB, &TRVOL IF &MESSAGE = " " GOTO S05 ASSIGN &ALARM = "YES" GOTO S01 * Check type of file; if object, set VARIABLES = YES ***************** S05: ASSIGN &OPTVAR = "NO " RUN READFDR IN USERSUBS [ on volume ] USING &INFIL, &INLIB, &INVOL, &MODE, "FT", &FILETYPE, &RC IF &FILETYPE = "O" ASSIGN &OPTVAR = "YES" IF &FILETYPE = "C" GOTO S06 ASSIGN &ALARM = "YES" ASSIGN &MESSAGE = &BLINKFAC !! "Input file not a program or procedure - please re-enter" * Set up trace function ********************************************** S06: ASSIGN &MESSAGE = &BRITEFAC !! &INFIL !! " successfully completed" TRACE INTO &TRFIL IN &TRLIB ON &TRVOL, RESOURCES = YES, SCRATCH = &OPTSCR, STATEMENTS = RUN, VARIABLES = &OPTVAR * Run program or procedure with TRACE on ***************************** S07: RUN &INFIL IN &INLIB ON &INVOL ERROR EXIT IS S08 CANCEL EXIT IS S08 S08: TRACE END ASSIGN &RC = S07 IF &RC = 0 GOTO S00 ASSIGN &ALARM = "YES" ASSIGN &MESSAGE = &BLINKFAC !! &INFIL !! " ended with return code " !! &RC GOTO S01 * OPTION: Run DISPMANY *********************************************** @14: RUN DISPMANY IN USERAIDS [ on volume ] ENTER INPUT LIBRARY = &TRLIB, VOLUME = &TRVOL ENTER INPUT 16 ASSIGN &ALARM = "NO " ASSIGN &MESSAGE = "DISPRINT completed" GOTO S01 @16: RETURN