[Access to Wang masthead]

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:

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

  [ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]  


Copyright © 1987 Dennis S. Barnes
Reprints of this article are permitted without notification if the source of the information is clearly identified