Introduction to SoftSpy

SoftSpy is a comprehensive system that allows the dynamic execution and collection of information concerning all aspects of User Language requests. It provides the information you need to quickly debug applications, learn how they operate, perform thorough quality assurance testing, identify and eliminate performance bottlenecks, and learn the general underlying principles behind good performance.

The heart of SoftSpy is a highly efficient kernel that gathers detailed statement level data in real-time while your application runs. You can interactively examine this data to obtain exactly the information you need.

An overview of SoftSpy follows. For more documentation on installing and using SoftSpy, see the SoftSpy category.

Interactive debugging

SoftSpy debugging provides the detailed information required to quickly and efficiently pinpoint the precise cause of a problem. It shows the exact statement causing a run-time error, the values of all program variables and data, and the history of statements executed prior to the error.

Application understanding

Understanding how an application works requires that you run the application to learn the user interface. It also requires that you study the procedures and data used by the application.

SoftSpy lets you quickly learn how applications work by integrating these activities together. You can clearly see which procedures are responsible for which portions of the user interface, and you can watch the interaction between the program and the data.

Quality Assurance testing

SoftSpy enables you to systematically test your applications. It shows you which statements have been tested and which statements have not been tested. SoftSpy also determines if untested code is really dead code (for example, code that is branched around or subroutines that are not called). This information lets you know if there are significant gaps in your testing effort. SoftSpy also lets you alter the flow of control in an executing program so you can more easily test all code paths.

Performance tuning

SoftSpy shows detailed performance characteristics of individual statements within User Language requests. Consumption of resources such as CPU time, page reads, disk reads and writes, CCATEMP, and server tables are all available on a statement by statement basis. Total use, percentages, or averages can be displayed, and histograms can show relative use graphically.

Education

SoftSpy can easily display performance information during normal testing of User Language requests. It is easy to observe how well a chosen approach works, which helps in learning the most efficient way to work with Model 204.

SoftSpy components

SoftSpy consists of four distinct optional components that share a common basic environment. The components are shown in the following figure.

SoftSpy components

Each component provides comprehensive capabilities in the indicated area.

• The Interactive Debugging option provides facilities for interactively debugging applications and for understanding how applications work.
• The Quality Assurance option supports QA testing.
• The Performance Tuning option supports both performance tuning and the education of users in performance factors.
• The Error Auditing option provides facilities to audit and diagnose errors that occur when a SoftSpy session is not active.

Basic SoftSpy environment

The basic SoftSpy environment provides many capabilities that are shared by all SoftSpy options.

Basic SoftSpy commands

Commands to perform the following functions are provided with all options.

• Turn SoftSpy on and off.
• Interactively execute a User Language request statement by statement.
• Execute an application until a user specified condition occurs, or until an interrupt such as an error occurs.
• Set and clear break points that will interrupt request evaluation when they are encountered.
• View the source code of the currently executing request (with all includes expanded) using a comprehensive set of scrolling commands.
• Define and manipulate windows that display information to be monitored on an ongoing basis.
• Add columns to the source code display that show detailed statement by statement information.
• Produce printed reports containing any information that can be displayed to the terminal.
• Assign frequently used commands to program function keys.
• Tailor the product by defining new commands using a powerful macro definition facility.
• Obtain help using a context-sensitive online facility.
• Configure the SoftSpy environment and define privileges of users.

SoftSpy data

SoftSpy provides access to a large variety of data. Access to most data is based on whether the optional feature that provides it is available. However, the following generic information is provided with all options:

• The name of the current subsystem.
• The name of the procedure and the procedure file containing the current request.
• The number of source lines in the current request, and the text, include level, nesting level, and line type of each line.
• A graphic representation of both the nesting and include levels.
• The current line being executed.
• Whether an update is in progress.
• Model 204 parameter values.

AUDIT option

Debugging run-time errors in User Language requests in a production environment can be a frustrating and time-consuming process.

The SoftSpy Audit option provides the detailed information required to debug run-time errors in User Language requests and quickly and efficiently pinpoint the cause of the problem.

Run-time errors

With the SoftSpy Audit feature enabled in your production environment, additional audit messages are produced when an error occurs during the evaluation of a User Language request. These messages identify the exact location that the error occurred within the request. Using this information in conjunction with the SoftSpy Audit environment you are quickly able to locate the statement causing the problem.

The sample below shows a segment of a Model 204 audit trail containing a typical divide by zero run-time error with the additional SoftSpy Audit information.

Audit trail with divide by zero error and SoftSpy audit information

The sample screen below shows the program that caused the divide by zero error above using the SoftSpy Audit environment.
In the Audit environment you can quickly identify the statement that caused the problem.

Audit environment showing line causing divide by zero error

Option features

The audit error option provides a number of features that augment the basic SoftSpy environment to provide a robust run-time error debugging environment.

Commands

• Establish the interactive audit error environment.
• Enable and disable auditing additional debugging information when SoftSpy is not in use.
• Display the User Language line causing a run-time error by utilizing SoftSpy audit information.

SoftSpy data

Information about the following types of operands is provided:

• Quad offset of the statement causing a run-time error.

DEBUG option

The DEBUG option provides the detailed information required to debug User Language requests and quickly and efficiently pinpoint the cause of a problem.

Run-time errors

SoftSpy lets you quickly track down run-time errors. After intercepting a typical error like divide by zero, SoftSpy displays a detailed diagnostic screen.

The name of the request being evaluated is shown on the second line of the screen followed by a window into the complete request with all includes expanded.

The current line (indicated by => in the prefix area) is positioned on the line that caused the error. The values of variables at the time of the error are displayed in the monitor window.

Interception of a divide by zero error

56 of 81 Next 56 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN DEMOPROC I DIVIDE ============================================================================================= NEST == \------- END FOR ----------MONITOR---------- == - %AVGORDER='' - == **************************** - %TOTALPRICE=1110.45 - == * CALC: AVERAGE ORDER SIZE * > %COUNT=0 - == **************************** - - == - - == /------- IF ( %OCOUNT NE 0 ) THEN - - => | %AVGORDER = %TOTALPRICE/%COUNT - - == |/------ IF %AVGORDER > 1000 THEN - - == || PRINT 'AVERAGE ORDER: ' - - - == || AND %AVGORDER WITH '*' - - == |>------ ELSE --------------------------- == || PRINT 'AVERAGE ORDER: ' AND %AVGORDER == |\------ END IF == \------- END IF => SPY.132: Evaluation error: M204.0554: DIVIDE BY ZERO. 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=DISPLAY 12=RETRIEVE

If you need additional information, you can easily examine the values of any variables, look at any portion of the program, or find out the sequence of statements executed prior to the error.

Compilation errors

SoftSpy also simplifies tracking down compilation errors. When they occur SoftSpy displays the User Language request. Compilation error messages are embedded within the request immediately following the offending statement.

The current line is positioned on the first line that contains a syntax error. Function keys are provided to jump forward to the next line containing an error or backward to the previous error line.

Interception of compilation errors

92 of 121 Next 1 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN DEMOPROC I COMP_ERROR ================================================================================== NEST == == /------- FOR EACH RECORD ON LIST LIST1 == |/------ IF COLOR ='BLUE' THEN == || %BLUE_CNT = %BLUE_CNT + 1 == |>------ ELSEIF COLOR = 'RED' THEN == || %RED_CNT = %RED_CNT + 1 == ||/----- IF YEAR = '93' THEN => ||| %RED94_CNT = %RED93_CNT + 1 == ||| M204.0595: UNDECLARED VARIABLES ARE NOT PERMITTED WITH THE UNDEFI == ||>----- ELSEIF YEAR = '94' THEN == ||| %RED94_CNT = %RED94_CNT + 1 == ||| ENDIF == ||| M204.0229: INVALID STATEMENT == ||\----- END FOR == || M204.1532: END IF EXPECTED, NOT END FOR => 1=HELP 2=WINDOW 3=QUIT 4=LEFT 5=RIGHT 7=BACKWARD 8=FORWARD 9=REPEAT 10=-ERROR 11=+ERROR 12=RETRIEVE

Application understanding

Understanding how an application works requires that you run the application to learn the user interface. It also requires that you study the procedures and data used by the application.

SoftSpy allows you to quickly learn how applications work by integrating these activities together. You can clearly see which procedures are responsible for which portions of the user interface, and you can watch the interaction between the program and the data. Seeing this interaction allows rapid in-depth understanding of an application.

SoftSpy also makes it easy to decipher applications written using statement numbers.

Option features

The interactive debugging option provides a number of features that augment the basic SoftSpy environment to provide a robust interactive debugging environment.

Commands

• Establish the interactive debugging environment.
• Scroll forward and backward among statements with compilation errors.
• Scroll backward and forward in the history of previously executed statements.
• Establish actions to perform when compilation or run-time errors are detected.
• Modify the value of fields, global variables and percent variables.

SoftSpy data

Information about the following types of operands is provided:

• fields
• global variables
• image items
• menu items
• percent variables
• screen items
• $ERRMSG
• $STATUS
• $STATUSD

QA option

High quality applications can be delivered only when thorough quality assurance testing is part of the application development process.

However, even the most carefully designed test plans inevitably have some gaps in their coverage.

SoftSpy allows a new approach to testing. It can precisely identify which statements have been tested and which statements have not been tested. This allows you to test your application and determine afterward if test coverage was complete.

You can then adjust your test plans based upon this feedback. The result is your ability to test applications more rigorously in less time.

Even when you know what code is untested, it might be difficult to construct test cases for all possible code paths. SoftSpy lets you alter the flow of control in an executing User Language procedure. This permits complete testing more easily and is especially useful when testing error handling code since appropriate test cases are often difficult to construct.

QA test coverage profile

SoftSpy can produce a detailed quality assurance test coverage profile. A message summarizes how thoroughly the current request has been tested.

The column labeled "U" contains the letter "U" for each line with an untested executable statement. If an executable statement has been tested then the column labeled "TIMES TESTED" indicates the number of times it was executed.

Quality Assurance test coverage profile

39 of 65 Next none SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG3 =============================================================================== TIMES LINE R U TESTED == 32 R 1170 PLACE RECORD ON LIST LIST1 == 33 R 1170 %COUNT10 = %COUNT0 == 34 R 1170 %COUNT11= %COUNT1 == 35 R 903 ELSEIF VEHICLE PREMIUM <501 THEN == 36 R 794 %COUNT2 = %COUNT2 + 1 == 37 R 794 PLACE RECORD ON LIST LIST2 == 38 R 109 ELSEIF VEHICLE PREMIUM >2000 THEN => 39 R U %COUNT3 = %COUNT3 + 1 == 40 R U PLACE RECORD ON LIST LIST3 == 41 R U %TMAKE = MAKE == 42 R U %TYEAR = YEAR == 43 END IF == 44 R 2073 END FOR == 45 R 1 STOP => 31 OF 35 REACHABLE STATEMENTS TESTED, 14 UNREACHABLE STATEMENTS 1=HELP 2=PRINT 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=-UNTESTED 11=+UNTESTED 12=RETRIEVE

Function keys are provided to allow you to move forward and backward among untested statements. You can also print the test coverage profile for review at a later time.

Unreachable statements

It is possible to have "dead" or unreachable code in requests. For example, code that is unconditionally branched around is unreachable. Similarly, code in a subroutine that can never be called is also unreachable.

SoftSpy can perform a complete flow analysis of your request in order to identify unreachable code. This allows statements to be classified as either tested, untested and unreachable, or untested and reachable. The presence of untested statements that are reachable indicates further testing is required.

The column labeled "R" indicates whether an executable statement is reachable or unreachable.

Unreachable statements

47 of 65 Next none SoftSpy for Model 204 01 SEP 2012 12:00:00 IN DEMOPROC I COVERAGE ============================================================================= TIMES LINE R U TESTED == 40 R 100 PLACE RECORD ON LIST LIST3 == 41 R 100 %TMAKE = MAKE == 42 R 100 %TYEAR = YEAR == 43 END IF == 44 R 2073 END FOR == 45 R 1 STOP == 46 U U PRINT 'TOTAL NUMBER OF RED CARS =' AND %RED_CNT => 47 COUNT750.TOTAL: SUBROUTINE == 48 U U %COUNT750 = %COUNT750 + 1 == 49 U U IF %TMAKE = 'BMW' AND %TYEAR = 1994 THEN == 50 U U %BMW94 = %BMW94 + 1 == 51 END IF == 52 U U RETURN == 53 U U END SUBROUTINE COUNT750.TOTAL => 1=HELP 2=PRINT 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=-UNTESTED 11=+UNTESTED 12=RETRIEVE

Option features

The quality assurance testing option provides a number of features that augment the basic SoftSpy environment to provide a robust quality assurance testing environment.

Commands

• Establish the quality assurance testing environment.
• Jump to and execute any statement.
• Exit loops early.
• Advance loops to the next iteration.
• Return from subroutines.
• Force the outcome of expressions.
• Scroll forward and backward among untested statements.
• Scroll forward and backward among unreachable statements.
• Initiate or terminate the collecting of quality assurance data.
• Add or remove columns from the source program display showing quality assurance data.

SoftSpy data

The following information is provided:

• Whether a statement is reachable or unreachable.
• Whether a statement has or has not been tested.
• The number of times a statement has been tested.

TUNE option

SoftSpy provides the information required to tune User Language applications and quickly track down performance bottlenecks. SoftSpy shows precisely which lines within requests consume the most system resources.

SoftSpy also provides detail to identify the underlying activities associated with system level resource consumption. This information enables you to quickly determine the root cause of performance problems.

Performance profile

SoftSpy lets you generate detailed performance profiles. Performance profiles can be tailored using an extensive repertoire of statistics that show all facets of an application's behavior. Resource use can also be displayed graphically using histograms.

For example, a performance profile can have a "CPU" column that shows the total milliseconds of CPU time and an "AVG CPU" column that shows the average milliseconds of CPU time spent executing each statement. A "PAGE REQ" column can show the number of page requests performed by the disk buffer monitor for each statement.

This type of performance profile shows statements with excessive CPU consumption. It also shows statements that generate excessive page requests. Excessive page requests pinpoint performance-related problems such as the thrashing of images in and out of the buffer pool. This detailed information can explain the cause of a CPU or I/O bottleneck.

Performance Profile

48 of 73 Last 73 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG5 ============================================================================= AVG PAGE CPU CPU REQ == REPEAT WHILE NOT %EOF == 288 .116 2480 READ IMAGE DETAIL FROM DETAIL == 43 .017 IF $STATUS NE 0 THEN == 1 .025 IF $STATUS EQ 1 THEN %EOF = 1 == ELSE JUMP TO INPUT_ERROR == END IF == END IF => 113 .046 20 IDENTIFY IMAGE DETAIL == 161 .065 2480 %RECODE:TRD.CUST.ID = %DETAIL:TRD.CUST.ID == 208 .084 4960 %RECODE:TRD.TRIP.YEAR.QTR = %DETAIL:TRD.TRIP.YEAR.QTR == 254 .102 4960 %RECODE:TRD.TRIP.NUMBER = %DETAIL:TRD.TRIP.NUMBER == 221 .089 4960 %RECODE:TRD.GAME.ID = %DETAIL:TRD.GAME.ID == == 122 .049 WRITE IMAGE RECODE ON RECODE => 1=HELP 2=PRINT 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=-CPU 11=+CPU 12=RETRIEVE

CCATEMP usage

In addition to all normal statistics, SoftSpy can show CCATEMP use by line. The use of CCATEMP is a critical performance factor. Excessive use causes buffer pool thrashing that becomes much worse as overall system load increases. Monitoring CCATEMP use lets you see the real problem, even on a lightly loaded system.

Performance profile with CCATEMP use and histograms

2 of 29 Last 29 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG6 ============================================================================= PAGE CCA PAGE REQ CPU REQ TEMP HISTOGRAM == BEGIN => 137 561 29 ********** FDORD: IN CLIENT1 FDWOL ZIP_CODE IS IN RANGE - == FROM '02190' TO '02192' == END FIND == == 1 * FOR EACH RECORD IN FDORD == 1 30 * IF DATE_PURCHASED > %DATE THEN == 2 %CURRENT = %CURRENT + 1 == ELSE == %HISTORY = %HISTORY + 1 == END IF == 2 58 ** END FOR == 1 -29 RELEASE RECORDS IN FDORD == => LARGEST CPU VALUE IS 137 (95.804% OF THE TOTAL) 1=HELP 2=PRINT 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=-CPU 11=+CPU 12=RETRIEVE

Server table usage

SoftSpy can show detailed statement level usage of server tables. Cumulative server table use can be shown for all server tables, and individually for tables such as QTBL and VTBL. This line by line information allows you to understand and optimize an application's server table use.

Server table usage profile

29 of 88 Last none SoftSpy for Model 204 01 SEP 2012 12:00:00 IN DEMOPROC I TABLES ============================================================================= CMPL CMPL CMPL SERV QTBL VTBL == 9129 304 744 IF %Y = 0 THEN == 9225 352 780 %X = $SETG('PRINT COUNT',0) == 9241 368 780 ELSE - == 9337 416 816 %X = $SETG('PRINT COUNT',1) == 9337 416 816 END IF == 9409 436 856 FND: IN VEHICLES FIND ALL RECORDS == 9461 472 872 END FIND => 9497 492 888 FOR EACH RECORD IN FND == 9593 560 916 IF VEHICLE PREMIUM < 251 THEN == 9641 608 916 %COUNT1 = %COUNT1 + 1 == 9681 624 928 PLACE RECORD ON LIST LIST1 == 9737 640 956 %COUNT10 = %COUNT0 == 9753 656 956 %COUNT11 = %COUNT1 == 9865 740 984 ELSEIF VEHICLE PREMIUM <501 THEN => 1=HELP 2=PRINT 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=PAGE REQ 11=FIND STMT 12=RETRIEVE

Performance information

SoftSpy lets application developers display performance information during the normal testing of User Language requests. Observing performance data for a chosen approach is helpful in learning the most efficient way to work with Model 204.

Option features

The interactive performance tuning option provides a number of features that augment the basic SoftSpy environment to provide a robust performance tuning environment.

Commands

• Establish the interactive performance tuning environment.
• Initiate or terminate the collecting of performance data.
• Scroll to statements in a request based on relative resource consumption.
• Add or remove columns from the source program display showing performance data. Totals, averages, percentages, and histograms that show relative use can be displayed.

SoftSpy data

A variety of performance-related information is available:

• Compile time usage by line for individual server tables and for all server tables combined.
• Total, average, percentage or histogram by statement for all performance-related Model 204 statistics including CPU time, page reads, and disk reads and writes.
• Current value of any Model 204 statistic.
• Average usage by statement of CCATEMP pages.
• Current CCATEMP usage.
• CCATEMP usage for a specified found set, sort set, or record list.
• CCATEMP usage for the transaction backout log, the pending update pool, all found sets, all sort sets, or all record lists.

Documentation notation conventions

Standard notation conventions, used throughout the SoftSpy wiki pages, are summarized in the following table:

Convention	Description
KEYWORD	Keywords that must appear exactly as indicated are shown in uppercase.
placeholder	Placeholders for substituted text, or the names of placeholders, are shown in lowercase italic.
[ OPTIONAL ]	Optional items are enclosed in square brackets.
{ REQUIRED } REQUIRED	Required items are either enclosed in braces or are not enclosed in either square brackets or braces.
	An optional set of items are stacked vertically and enclosed in square brackets. At most one item may be selected. If there is a default item, then that item is underlined.
	A required set of items are stacked vertically and enclosed in braces. Exactly one item must be selected.
...	Ellipses (three dots) indicate that the preceding item can be repeated.