SoftSpy environments

SoftSpy enables you to perform a large variety of different types of work. Work is performed within environments designed to meet the requirements of particular tasks.

Interactive evaluation environments

Five environments are designed to support the interactive evaluation of User Language requests. These environments are available after you issue the SPY ON command to turn SoftSpy on. Once SoftSpy is turned on all Model 204 commands except BEGIN and MORE operate exactly as they would without SoftSpy. The BEGIN and MORE commands cause control to be passed to SoftSpy so that you can control and monitor the evaluation of User Language requests. These environments are summarized in the following table.

Environment	Description
AUDIT	Use audit information to find a User Language request error.
COMPILE_ERROR	Examine User Language requests containing compilation errors.
DEBUG	Interactively debug User Language requests.
QA	Perform quality assurance testing of User Language requests.
TUNE	Interactively tune User Language requests.

Each of these environments is tailored toward a specific task. However, they all share a common screen infrastructure. The basic screen components are summarized in the following figure.

SoftSpy Screen Components

A brief description of each SoftSpy screen component illustrated in the preceding figure is given below.

Component	Description
Active window	The window in which scrolling commands are performed. Highlighted equal sign (=) characters are used as border characters for the active window. Dim hyphen (-) characters are used as border characters for all other windows.
Command line	A line on which SoftSpy commands may be entered. It appears directly below the source window, and begins with =>.
Current line	The current line, or position, within a window. There is a distinct current line for each window. It is indicated with the > character.
Current line number	The current line number in the source window.
Date and time	The current date and time.
Function keys	Labels that identify the actions performed by the program function keys.
Execution position	An indicator of either the next statement to execute or the last statement executed.
Message area	A line on which SoftSpy displays error and informational messages.
Prefix area	The left border of the source window. SoftSpy prefix commands can be entered in this area.
Procedure	The name of the current procedure and procedure file.
SHOW columns	Columns created by the SoftSpy SHOW command that show detailed line by line information about the source program.
Source window	A window containing the current User Language request with all includes expanded. The portion of the window surrounding the current line is displayed on the screen.
Subsystem	The name of the current subsystem, if any.
Total lines	The total number of lines in the source window. This is a count of all lines in the current user language request, including lines that were included, in the current User Language request.
Watch window	A window used to monitor the value of operands on an ongoing basis during request execution.

Administrative environments

SoftSpy provides five environments that are useful for various administrative tasks. These environments allow you to examine the facilities available in SoftSpy, and customize SoftSpy to meet your needs and the needs of your organization. These environments are summarized in the following table.

Environment	Description
BROWSE	Browse an access control list or a macro.
CONFIG	Edit the SoftSpy system configuration.
EDIT	Create or edit an access control list or a macro.
HELP	Obtain SoftSpy online help.
LIST	Display a list of macros or a list of access control lists.

SoftSpy contexts

The ten SoftSpy environments are based upon seven contexts. Each context represents one of the seven fundamental SoftSpy activities. The SoftSpy contexts are summarized in the following table.

Context	Description
BROWSE	Browse an access control list or a macro.
COMPILE_ERROR	Examine User Language requests containing compilation errors.
CONFIG	Edit the SoftSpy system configuration.
EDIT	Create or edit an access control list or a macro.
EVAL	Interactively execute User Language requests.
HELP	Obtain SoftSpy online help.
LIST	Display a list of macros or a list of access control lists.

Each context except the EVAL context has one corresponding SoftSpy environment. The EVAL context corresponds with the four SoftSpy environments summarized below.

Environment	Description
AUDIT	Use audit information to find a User Language request error.
DEBUG	Interactively debug User Language requests.
QA	Perform quality assurance testing of User Language requests.
TUNE	Interactively tune User Language requests.

The EVAL context environments represent specializations of the fundamental activity of interactively evaluating User Language requests. Each environment is designed around one of the optional feature sets available with SoftSpy. However, there is no intrinsic reason the activities associated with each feature set need to be separated. In fact, it is often desirable to look at quality assurance or performance related information while performing interactive debugging. You can customize these environments, or create new environments, to meet your specific requirements.

Factors which vary from context to context include command availability, screen layout, program function key definitions, prefix commands, and operands.

Interacting with SoftSpy

You can interact with SoftSpy in one of three ways:

1. Press a program function key. The action associated with the program function key will be performed. Each environment has its own set of program function key actions that are described in this chapter.
2. Press the Enter key. Any SoftSpy command entered on the SoftSpy command line will be processed. The “Commands and Macros” chapter describes the available commands.
3. Enter prefix commands on one or more lines in the prefix area and press the Enter key or a program function key. Each prefix command will be processed in order from first to last prefix line. Each environment has its own set of prefix commands that are described in this chapter. After the prefix commands are processed, the normal action performed when the enter key or a program function key is pressed, as described above, is performed.

Command availability

Not all SoftSpy commands can be used in all contexts. For example, many commands are only available in the EVAL or COMPILE_ERROR context. Check the RESTRICTION clause information in

this reference to see if access to a particular command is limited by context.

Screen layout

Screen layout varies from one environment to another. All of the EVAL context environments feature the source code of the request being evaluated. The BROWSE context displays a macro or access control list to browse. The HELP context displays on‑line help on SoftSpy topics, etc.

Program Function Key definitions

To best promote the work done in each environment, program function key definitions vary from one environment to another. The PF command is used to define program function key actions. Initial settings are provided in the PROFILE macro. Settings may be dynamically altered. For example, the AUDIT, DEBUG, TUNE, and QA environments dynamically alter PF key settings to meet their requirements.

Prefix commands

Prefix commands are shorthand commands that are specified in the prefix area of a line. The available prefix commands vary based on the context in which they are used. The description of each environment includes a list of prefix commands available in the environment.

---

AUDIT environment

Function	Interactively locate and debug User Language requests with run-time errors.
Restrictions	The audit option is required.
Description	The AUDIT environment is entered when the AUDIT macro is issued or when evaluation of a User Language request is suspended if the AUDIT macro was previously issued.

In the AUDIT environment, the source window contains the User Language request being evaluated prefixed with brackets showing statement nesting level and the cumulative QTBL usage for each statement. A monitor window in which operands can be watched is also present in the upper right corner of the screen. The focus of the current line is set to the next executable statement. The audit environment can be customized on an individual user basis. See the AUDIT macro for information on customization.

If a cancelling or non-cancelling evaluation time error occurs, execution is suspended, and all percent variables referenced by the line with the error are automatically added to the monitor window.

Audit Environment Screen

12 of 16 Next 1 SoftSpy for Model 204 20 JUL 2012 11:45:26 IN AEYPROC I TESN.LOGIN SUBSYSTEM DEMO ============================================================================= CMPL NEST QTBL == 20 CALL MAIN ----------MONITOR---------- == 52 %X = $SETG('NEXT','EXIT') - - == 52 - - == /------- 68 MAIN: SUBROUTINE - - == | 88 CALL DIVIDE.LOOP - - == \------- 96 END SUBROUTINE MAIN - - == 96 - - == /------- 112 DIVIDE.LOOP: SUBROUTINE - - == |/------ 172 FOR %I FROM 10 TO 0 BY -1 - - => || 220 %J = 10 / %I - - == |\------ 224 END FOR - - == \------- 232 END SUBROUTINE DIVIDE.LOOP --------------------------- == 232 == 276 END => 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=QUAD 12=RETRIEVE

Prefix commands

Cmd	Description
B	Set a break point on the prefix command line.
J	Alter the next statement to be executed to the first statement on the prefix command line and execute the statement. The Quality Assurance testing option is required.
/	Set the current line to the prefix command line.

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help.
PF2	WINDOW	Toggle the active window between the source and monitor windows.
PF3	QUIT	Quit evaluation of the current User Language request.
PF4	STEP	Resume request evaluation for a single statement, or for the number of statements specified on the command line. Stop evaluation if a break point, evaluation-time error, or a new request is encountered.
PF5	GO	Resume request evaluation until a break point, evaluation-time error, or a new request is encountered. If an expression is specified on the command line then evaluation is also suspended when the expression is satisfied. If FOREVER is specified on the command line then evaluation is resumed until a compile or evaluation time error occurs.
PF6	BREAK	Toggle a break point on or off on the line containing the cursor, or on the current line if the cursor is not positioned on a line in the request.
PF7	BACKWARD	Scroll backward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF10	WATCH	Watch the operands specified on the command line in the monitor window on an ongoing basis. If no operands are specified, watch any variables on the line containing the cursor, or on the current line if the cursor is not positioned on a line in the request.
PF11	QUAD	Find the line containing the QTBL offset specified on the command line and make it the current line. If a procedure name is specified following the QTBL offset then evaluation is first resumed until the specified procedure is reached.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also AUDIT

---

BROWSE environment

Function	Browse access control lists and macros.
Description	The BROWSE environment is invoked with the BROWSE ACL or BROWSE MACRO command. It supports examining access control lists and macros.

BROWSE Environment Screen

25 of 50 SoftSpy for Model 204 01 SEP 2012 12:00:00 BROWSE MACRO DISPLAY_WATCH ============================================================================= SET $I = $CURSOR_LINE('SOURCE') IF $I EQ 0 THEN SET $I = $CURRENT_LINE('SOURCE') DEFINE $TEXT STRING LEN 255 LOCAL SET $TEXT = $SOURCE_LINE_DATA('TEXT',$I) DEFINE $OPERAND STRING LEN 255 LOCAL DEFINE $RIGHT_PAREN STRING LEN 1 LOCAL SET $RIGHT_PAREN = ')' DEFINE $DELIMITERS STRING LEN 25 LOCAL SET $DELIMITERS = ',<>?/"{}\+=-()*& ' DEFINE $CHAR STRING LEN 1 LOCAL OPERAND_LOOP: SET $I = $INDEX($TEXT,'%') IF $I EQ 0 THEN JUMP TO DISPLAY_WATCH SET $TEXT = $SUBSTR($TEXT,$I) SET $I = $MATCH($TEXT,$DELIMITERS) IF $I THEN JUMP TO OPERAND_DELIMITER => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help.
PF2	PRINT	Print the macro or access control list.
PF3	QUIT	Quit the BROWSE environment.
PF4	TOP	Move to the start of the access control list or macro.
PF5	BOTTOM	Move to the end of the access control list or macro.
PF7	BACKWARD	Scroll backward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also BROWSE ACL, BROWSE MACRO

---

COMPILE_ERROR environment

Function	Locate syntax errors within User Language requests.
Restrictions	The interactive debugging option is required.
Description	The COMPILE_ERROR environment is automatically entered when a User Language request fails to compile successfully. Compilation error messages are embedded within the source window following the lines to which they pertain.

When the environment is entered, the active window is set to the source window and the current line is positioned on the first statement containing an error. A message stating that the request failed to compile appears on the message line.

COMPILE_ERROR Environment Screen

27 of 78 Next 1 SoftSpy for Model 204 01 SEP 1998 2012 12:00:00 IN QCPROC I MAN.FIG9 ============================================================================= NEST == \------- END FOR --------MONITOR------------ == == * - - == * PROCESS THE ORDER FILE - - == * COMPUTE THE TOTAL VALUE - - == * AND COUNT THE ORDERS. - - == * - - => FDORD: IN SSPYQA FD RECTYP = ORDER - - == M204.1265: NO SUCH FIELD NAME. FIELD - - == END FIND - - == * - - == %OCOUNT = 0 --------------------------- == /------- FOR EACH RECORD IN FDORD == | %OCOUNT = %OCOUNT + 1 == | CALL GET_PRICE( ITEM, %PRICE ) => SPY.131: A new request has failed to compile. 1=HELP 2=WINDOW 3=QUIT 4=LEFT 5=RIGHT 7=BACKWARD 8=FORWARD 9=REPEAT 10= ERROR 11=+ERROR 12=RETRIEVE

Prefix commands

Cmd	Description
/	Set the current line to the prefix command line.

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help for the COMPILE_ERROR environment.
PF2	WINDOW	Toggle the current active window.
PF3	QUIT	Quit the COMPIILE_ERROR environment.
PF4	LEFT	Scroll left the distance specified on the command line in the active window. FULL (which is the default) means the full width of the window, HALF means half the window width, MAX means to column one, and an integer indicates a number of columns.
PF5	RIGHT	Scroll right the distance specified on the command line in the active window. FULL (which is the default) means the full width of the window, HALF means half the window width, MAX means to the last column, and an integer indicates a number of columns.
PF7	BACKWARD	Scroll backward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF10	-ERROR	Move to the previous error in the source window.
PF11	+ERROR	Move to the next error in the source window.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

---

CONFIG environment

Function	Browse or edit the SoftSpy configuration.
Description	The CONFIG environment is entered with the EDIT CONFIG command. It is used to edit the SoftSpy configuration.

CONFIG Environment Definition Screen

1 of 2 SoftSpy for Model 204 01 SEP 21012 12:00:00 EDIT CONFIG ============================================================================= Square Brackets can be displayed on terminals (Y OR N) Y Privilege Access Control List Name M204 Ad Hoc ADMIN_______________ M204 Macro ____________________ Read ACL ADMIN_______________ Read Macro ____________________ SoftSpy Server ADMIN_______________ Spy On ____________________ Update ACL ADMIN_______________ Update Macro ADMIN_______________ => 1=HELP 3=QUIT 4=TOP 5=BOTTOM 6=SAVE 7=BACKWARD 8=FORWARD 9=REPEAT 10=ACLS 11=MACROS 12=RETRIEVE

CONFIG Environment Authorization Entry Screen

2 of 2 SoftSpy for Model 204 01 SEP 2012 12:00:00 EDIT CONFIG ============================================================================= SoftSpy Version 3.0C SoftSpy Serial Number 970253 Authorization Key EPPQMKFL Start Date __ ___ ____ Expiration Date 01 DEC 2012 Customer Name SoftSpy Trial CPU Model Number **** CPU Serial Number ****** Optional Features User Limit Permitted Operating Systems X Debugging ____ X DOS X Performance Tuning ____ X CMS X QA Testing ____ X MVS X Audit X MVS/ESA X MUSE Configuration Entry Editing Actions (X to request specified action) _ Delete this authorization entry _ Insert new authorization entry => 1=HELP 3=QUIT 4=TOP 5=BOTTOM 6=SAVE 7=BACKWARD 8=FORWARD 9=REPEAT 10=ACLS 11=MACROS 12=RETRIEVE

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help for the CONFIG environment.
PF3	QUIT	Quit the CONFIG environment.
PF4	TOP	Move to the first configuration screen.
PF5	BOTTOM	Move to the last configuration screen.
PF6	SAVE	Save the configuration and activate any inactive IODEV=55 SoftSpy server threads.
PF7	BACKWARD	Scroll backward one screen.
PF8	FORWARD	Scroll forward one screen.
PF9	REPEAT	Repeat the last command entered on the command line.
PF10	ACLS	Enter the LIST environment with a list of access control lists that match the pattern specified on the command line. If no pattern is specified then list all access control lists.
PF11	MACROS	Enter the LIST environment with a list of macros that match the pattern specified on the command line. If no pattern is specified then list all macros.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also EDIT CONFIG

---

DEBUG environment

Function	Interactively debug User Language requests.
Restrictions	The interactive debugging option is required.
Description	The DEBUG environment is entered when the DEBUG macro is issued or when evaluation of a User Language request is suspended if a DEBUG macro was previously issued.

In the DEBUG environment, the source window contains the User Language request being evaluated prefixed with brackets showing statement nesting level. A monitor window in which operands can be watched is also present in the upper right corner of the screen. The focus of the current line is set to the next executable statement. The debugging environment can be customized on an individual user basis. See the DEBUG macro for information on customization.

If a cancelling or non-cancelling evaluation time error occurs, execution is suspended, and all percent variables referenced by the line with the error are automatically added to the monitor window.

DEBUG Environment Screen

1 of 20 Next 1 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG12 ============================================================================= NEST => BEGIN ----------MONITOR---------- == %TOTALQTY IS FIXED > $UPDATE=0 - == - - == * FIND ALL CURRENT ORDERS - - == FDORD: - - == IN CLIENT1 FDWOL ZIP_CODE IS I - - == FROM '02190' TO '02190' - - == END FIND - - == - - == /------- FOR EACH RECORD IN FDORD - - == |/------ IF DATE_PURCHASED > %DATE THEN - - == || %CURRENT = %CURRENT + 1 --------------------------- == |>------ ELSE == || %HISTORY = %HISTORY + 1 == |\------ END IF => 1=HELP 2=WINDOW 3=QUIT 4=STEP 5=GO 6=BREAK 7=BACKWARD 8=FORWARD 9=REPEAT 10=WATCH 11=DISPLAY 12=RETRIEVE

Prefix commands

B	Description
J	Alter the next statement to be executed to the first statement on the prefix command line and execute the statement. The Quality Assurance testing option is required.
/	Set the current line to the prefix command line.

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help.
PF2	WINDOW	Toggle the active window between the source and monitor windows.
PF3	QUIT	Quit evaluation of the current User Language request.
PF4	STEP	Resume request evaluation for a single statement, or for the number of statements specified on the command line. Stop evaluation if a break point, evaluation-time error, or a new request is encountered.
PF5	GO	Resume request evaluation until a break point, evaluation-time error, or a new request is encountered. If an expression is specified on the command line then evaluation is also suspended when the expression is satisfied. If FOREVER is specified on the command line then evaluation is resumed until a compile or evaluation time error occurs.
PF6	BREAK	Toggle a break point on or off on the line containing the cursor, or on the current line if the cursor is not positioned on a line in the request.
PF7	BACKWARD	Scroll backward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line in the active window. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF10	WATCH	Watch the operands specified on the command line in the monitor window on an ongoing basis. If no operands are specified, watch any variables on the line containing the cursor, or on the current line if the cursor is not positioned on a line in the request.
PF11	DISPLAY	Display the current values of the operands specified on the command line. If no operands are specified, display any variables on the line containing the cursor, or on the current line if the cursor is not positioned on a line in the request.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also DEBUG

---

EDIT environment

Function	Create or edit access control lists or macros.
Description	The EDIT environment is entered with the EDIT ACL or EDIT MACRO command. It supports editing access control lists and macros.

EDIT Environment Screen

25 of 50 SoftSpy for Model 204 01 SEP 2012 12:00:00 EDIT MACRO DISPLAY_WATCH ===== ======================================================================= ===== SET $I = $CURSOR_LINE('SOURCE') ===== IF $I EQ 0 THEN SET $I = $CURRENT_LINE('SOURCE') ===== DEFINE $TEXT STRING LEN 255 LOCAL ===== SET $TEXT = $SOURCE_LINE_DATA('TEXT',$I) ===== DEFINE $OPERAND STRING LEN 255 LOCAL ===== DEFINE $RIGHT_PAREN STRING LEN 1 LOCAL ===== SET $RIGHT_PAREN = ')' ===== DEFINE $DELIMITERS STRING LEN 25 LOCAL ====> SET $DELIMITERS = ',<>?/''"{}\+= ()*& ' ===== DEFINE $CHAR STRING LEN 1 LOCAL ===== OPERAND_LOOP: ===== SET $I = $INDEX($TEXT,'%') ===== IF $I EQ 0 THEN JUMP TO DISPLAY_WATCH ===== SET $TEXT = $SUBSTR($TEXT,$I) ===== SET $I = $MATCH($TEXT,$DELIMITERS) ===== IF $I THEN JUMP TO OPERAND_DELIMITER => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 6=SAVE 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

Prefix commands

Cmd	Description
D	Delete the prefix command line. If a number is specified along with the prefix command then the specified number of lines are deleted.
I	Insert a line following the prefix command line. If a number is specified along with the prefix command then the specified number of lines are inserted.
"	Make a copy of the prefix command line following the prefix command line. If a number is specified along with the prefix command then the specified number of copies are made.
/	Set the current line to the prefix command line.

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help for the EDIT environment.
PF2	PRINT	Print the macro or access control list.
PF3	QUIT	Quit the EDIT environment.
PF4	TOP	Move to the start of the access control list or macro.
PF5	BOTTOM	Move to the end of the access control list or macro.
PF6	SAVE	Save the macro or access control list. The existing name is used unless a new name is specified on the command line.
PF7	BACKWARD	Scroll backward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also EDIT ACL, EDIT MACRO

---

HELP environment

Function	Provide interactive on-line help for SoftSpy.
Description	The HELP environment is entered with the HELP command. It provides access to SoftSpy's interactive on‑line help facility.

HELP Environment Screen

1 OF 6 SoftSpy for Model 204 01 SEP 2012 12:00:00 HELP PRINT ============================================================================= Select a topic by placing the cursor on a topic and pressing the HELP PF key PRINT ACL PRINT HELP PRINT LINE PRINT LIST PRINT MACRO PRINT WINDOW => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 6=QUIT HELP 7=BACKWARD 8=FORWARD 9=REPEAT 10=HELP MENU 11=HELP LIST 12=RETRIEVE

PF keys

Key	Label	Description
PF1	HELP	Provide help on the topic on which the cursor is positioned.
PF2	PRINT	Print the help topic.
PF3	QUIT	Quit the current help topic or return to any prior help topic.
PF4	TOP	Move to the start of the help topic.
PF5	BOTTOM	Move to the end of the help topic.
PF6	QUIT HELP	Quit all help topics and exit the HELP environment.
PF7	BACKWARD	Scroll backward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF10	HELP MENU	Provide a high level summary menu of available help topics.
PF11	HELP LIST	Provide a list of all available help topics.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also HELP

---

LIST environment

Function	Examine a list of access control lists or a list of macros.
Description	The LIST environment is entered with the LIST ACL or the LIST MACRO command. A scrollable list of access control lists or macros is displayed. Prefix commands can be used to perform operations on the members of the list.

LIST Environment Screen

1 OF 305 SoftSpy for Model 204 01 SEP 2012 12:00:00 LIST MACRO ============================================================================= UPDATE UPDATE UPDATE NAME LINES USERID DATE TIME > ALL_TYPES 23 STEVE 20 FEB 1992 16:42:59 = ALTPF 12 STEVE 18 JUN 1992 15:54:15 = ALTPF1 12 STEVE 18 JUN 1992 16:12:26 = ANT 5 ANTHONY 09 AUG 1994 12:44:16 = ANTHONY_ON_EVAL 19 ANTHONY 18 APR 1994 13:50:44 = ANTHONY_PROFILE 8 ANTHONY 19 JUL 1994 15:37:20 = A1 2 GEORGEW 03 AUG 1994 11:58:10 = B 1 KAREN 08 FEB 1994 15:16:36 = BKBM 2 ANTHONY 11 NOV 1993 16:59:50 = BN 41 MICHAEL 26 JUN 1994 14:58:59 = BOB_ARRAY 82 BOB 03 SEP 1993 12:38:41 = BOB_ARRAY_D 9 BOB 27 AUG 1993 08:21:18 = BOB_BREAKS 31 BOB 02 SEP 1993 10:41:14 = BOB_WATCH 9 BOB 23 AUG 1993 10:16:06 => 1=HELP 2=PRINT 3=QUIT 4=TOP 5=BOTTOM 7=BACKWARD 8=FORWARD 9=REPEAT 12=RETRIEVE

Prefix commands

Cmd	Description
B	Browse the access control list or macro on the prefix command line.
C	Copy the access control list or macro on the prefix command line. The name for the copy must be specified in the name field.
D	Delete the access control list or macro on the prefix command line.
E	Edit the access control list or macro on the prefix command line.
R	Rename the access control list or macro on the prefix command line. The new name must be specified in the name field.

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help for the LIST environment.
PF2	PRINT	Print the list.
PF3	QUIT	Quit the LIST environment.
PF4	TOP	Move to the start of the list.
PF5	BOTTOM	Move to the end of the list.
PF7	BACKWARD	Scroll backward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also LIST ACL, LIST MACRO

---

QA environment

Function	Perform interactive quality assurance testing of User Language requests.
Restrictions	The quality assurance testing option is required.
Description	The QA environment is entered when the QA macro is issued or when evaluation of a User Language request is suspended if a QA macro was previously issued.

In the QA environment, the source window contains the User Language request being evaluated prefixed with four columns. These columns show the line number, whether the statement is reachable or unreachable, whether the statement is untested, and the number of times the statement has been tested if it has been executed. The focus of the current line is set to the next executable statement. The quality assurance testing environment can be customized on an individual user basis. See the QA macro for information on customization.

Whenever evaluation of a User Language request is completed the current line is positioned on the first untested line. A message is displayed showing the number of statements that have been tested and the total number of statements that are reachable in the request. The message also identifies the number of unreachable or dead statements in the request.

QA Environment Screen

19 of 79 Next none SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG16 ============================================================================= TIMES LINE R U TESTED == 12 R 1000 IF ( %EOF ) THEN == 13 R 1 LOOP END == 14 END IF == 15 * == 16 * DISPATCH BASED ON TYPE == 17 * == 18 R 999 JUMP TO (ADD,UPDATE,DELETE) %TRAN_CODE => 19 R U JUMP TO INVALID == 20 U U %EOF = 0 == 21 * == 22 * PROCESS AN ADD == 23 * == 24 R 499 ADD: CALL ADDIT == 25 R 499 JUMP TO ENDLUP => 22 OF 29 REACHABLE STATEMENTS TESTED, 2 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

Prefix commands

Cmd	Description
B	Set a break point on the prefix command line.
J	Alter the next statement to be executed to the first statement on the prefix command line and execute the statement. The Quality Assurance testing option is required.
/	Set the current line to the prefix command line.

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help.
PF2	PRINT	Print the source window.
PF3	QUIT	Quit evaluation of the current User Language request.
PF4	STEP	Resume request evaluation for a single statement, or for the number of statements specified on the command line. Stop evaluation if a break point, evaluation-time error, end of request, or a new request is encountered.
PF5	GO	Resume request evaluation until a break point, evaluation-time error, end of request, or a new request is encountered. If an expression is specified on the command line then evaluation is also suspended when the expression is satisfied. If FOREVER is specified on the command line then evaluation is resumed until a compile or evaluation time error occurs.
PF6	BREAK	Toggle a break point on or off on the line containing the cursor, or on the current line if the cursor is not positioned on a line in the request.
PF7	BACKWARD	Scroll backward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF10	‑UNTESTED	Scroll backward to the previous untested line. This function key can be changed to scroll based on different criteria using the SCROLL
PF11	+UNTESTED	Scroll forward to the next untested line. This function key can be changed to scroll based on different criteria using the SCROLL macro.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also QA

---

TUNE environment

Function	Perform interactive performance tuning of User Language requests.
Restrictions	The interactive performance tuning option is required.
Description	The TUNE environment is entered when the TUNE macro is issued or when evaluation of a User Language request is suspended if a TUNE macro was previously issued.

In the TUNE environment, the source window contains the User Language request being evaluated, prefixed with three columns. These columns show the CPU time used in milliseconds, the number of page requests (DKPR), and the average change in CCATEMP scratch file usage. The focus of the current line is set to the last statement executed. The performance tuning environment can be customized on an individual user basis. See the TUNE macro for information on customization.

Whenever evaluation of a User Language request is completed, the current line is positioned on the first line with the largest CPU consumption. A message is displayed indicating the percent of the total CPU consumption used by the line. Program function keys 10 and 11 are temporarily altered to allow scrolling through the request based on the level of CPU consumption. They are reset to their normal function when evaluation of a new request is begun.

TUNE Environment Screen

23 of 76 Last 76 SoftSpy for Model 204 01 SEP 2012 12:00:00 IN QCPROC I MAN.FIG17 ============================================================================= PAGE CCA CPU REQ TEMP == %STATS:COUNTERS( %I ) = 0 == END FOR == * == * PROCESS THE ORDER FILE == * COMPUTE THE TOTAL VALUE == * AND COUNT THE ORDERS. == * => 6 138 1 FDORD: IN SSPYQA FD RECTYPE = ORDER == END FIND == %OCOUNT = 0 == 1 FOR EACH RECORD IN FDORD == %OCOUNT = %OCOUNT + 1 == 1 CALL GET_PRICE( ITEM, %PRICE ) == 1 %TOTALPRICE = %TOTALPRICE+%PRICE*QTY => LARGEST CPU VALUE IS 6 (66.667% 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

Prefix commands

Cmd	Description
B	Set a break point on the prefix command line.
J	Alter the next statement to be executed to the first statement on the prefix command line and execute the statement. The Quality Assurance testing option is required.
/	Set the current line to the prefix command line.

PF keys

Key	Label	Description
PF1	HELP	Invoke SoftSpy help.
PF2	PRINT	Print the source window.
PF3	QUIT	Quit evaluation of the current User Language request.
PF4	STEP	Resume request evaluation for a single statement, or for the number of statements specified on the command line. Stop evaluation if a break point, evaluation-time error, end of request, or a new request is encountered.
PF5	GO	Resume request evaluation until a break point, evaluation-time error, end of request, or a new request is encountered. If an expression is specified on the command line then evaluation is also suspended when the expression is satisfied. If FOREVER is specified on the command line then evaluation is resumed until a compile or evaluation time error occurs.
PF6	BREAK	Toggle a break point on or off on the line containing the cursor, or on the current line if the cursor is not positioned on a line in the request.
PF7	BACKWARD	Scroll backward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF8	FORWARD	Scroll forward the distance specified on the command line. FULL (which is the default) means one screen, HALF means a half screen, and an integer indicates a number of lines.
PF9	REPEAT	Repeat the last command entered on the command line.
PF10	PAGE REQ	(Function during request evaluation.) Resume request evaluation until a statement that examines a disk buffer page is encountered, or until a break point, evaluation-time error, or start or end of request is encountered.
PF10	‑CPU	(Function after request evaluation.) Scroll backward to a line with the same CPU value as the current line, or move to the last line with the next larger CPU value. This function key can be changed to scroll based on different criteria using the SCROLL macro.
PF11	FIND STMT	(Function during request evaluation.) Resume request evaluation until a find statement is encountered, or until a break point, evaluation-time error, or start or end of request is encountered.
PF11	+CPU	(Function after request evaluation.) Scroll forward to a line with the same CPU value as the current line, or move to the first line with the next smaller CPU value. This function key can be changed to scroll based on different criteria using the SCROLL macro.
PF12	RETRIEVE	Retrieve prior commands entered on the command line.

See Also TUNE

---

Tailoring environments

SoftSpy is designed to be easy to customize. When you enter SoftSpy the PROFILE macro is executed.

PROFILE macro

The PROFILE macro establishes the structure of most SoftSpy environments. When the PROFILE macro completes execution it runs a macro named userid_PROFILE, where userid is your user id, if such a macro exists. You can make installation-wide changes to SoftSpy by changing the PROFILE macro.

You can make changes that affect only you by creating or modifying a userid_PROFILE macro.

DEFAULT PRINTER command

The PROFILE macro specifies certain defaults in addition to defining various environments. For example, it contains a DEFAULT PRINTER command that specifies the default destination for print output. The command included in the PROFILE macro distributed with SoftSpy is DEFAULT PRINTER TERMINAL. Rocket Software recommends that the default be changed to specify a hard-copy print destination that is convenient for most SoftSpy users at your installation. If the system-wide default print destination specified in the PROFILE macro is not convenient for you, you should create a userid_PROFILE macro that includes a DEFAULT PRINTER command for a convenient destination.

$SKIP_SUBSYSTEMS variable

Another default value set in the PROFILE macro is the value of the $SKIP_SUBSYSTEMS variable. This variable contains a list of subsystems that should be automatically skipped over, and not interactively executed, by SoftSpy. The PROFILE macro distributed with SoftSpy specifies the SSTEST and SOFTSPY subsystems. The names of additional administrative or tool subsystems that you might use when SoftSpy is turned on, but which you would not want to interactively execute, should be added to the list. Subsystems that are used system-wide should be added in the PROFILE macro. Subsystems that you alone want to skip should be added in your userid_PROFILE macro. Each subsystem name must be followed by a blank, and the list cannot be more than 255 characters long.

$END_EVAL_SCROLL_TOP variable

The $END_EVAL_SCROLL_TOP variable is used to control scrolling at end of evaluation in the QA and TUNE environments. The PROFILE macro sets this variable to one, or true. In the QA environment this causes the current line to be automatically positioned on the first untested statement at end of evaluation. In the TUNE environment it causes the current line to be automatically positioned on the first statement with the largest CPU consumption. If the variable is set to zero, the current line is left positioned on the last statement executed at the end of evaluation.

PF commands

The primary content of the PROFILE macro is PF commands that define function key settings. System-wide changes to function keys can be made by changing the PROFILE macro. Personal changes to function keys can be made by adding appropriate PF commands to your userid_PROFILE macro.

AUDIT, DEBUG, QA, and TUNE macros

The AUDIT, DEBUG, QA, and TUNE environments are defined by the AUDIT, DEBUG, QA, and TUNE macros. Installation-wide changes to these environments can be made by changing the corresponding macro. Each of these macros also invokes a user-specific macro, if one exists, to allow you to make changes that affect only you. The user-specific macros are named userid_AUDIT, userid_DEBUG, userid_QA, and userid_TUNE.

One way these environments can be changed is by altering the columns that are shown in the source window. For example, if you always want a column showing the EXECOUNT statistic in the DEBUG environment, you can add the command SHOW EXECOUNT to your userid_DEBUG macro. If you want to eliminate the nesting level column, you can include the command UNSHOW * before any SHOW commands for columns you do want.

SCROLL and related commands

The SCROLL command is particularly useful for tailoring the QA and TUNE environments. It controls the default action of program function keys 10 and 11 in these environments.

The QA macro issues a SCROLL UNTESTED command. This causes function keys 10 and 11 to scroll backward and forward to the next untested statement. If you want to change the default to scroll backward and forward to the next unreachable statement instead, you can include a SCROLL UNREACHABLE command in your userid_QA macro.

The TUNE macro issues a SCROLL MAX CPU command. This causes function key 10 to scroll backward to the line with the next smaller CPU usage and function key 11 to scroll forward to the line with the next larger CPU usage. If you want to change the default to scroll based on the number of page requests instead, you can include a SCROLL MAX DKPR command in your userid_TUNE macro.