Primary Commands

ABEND (ABE)

The ABEND command ends the current Code Debug CICS function and transfers to the Exit Session screen (X).

From the Exit Session screen (X), you may choose to produce either a Transaction Abend or Abend-AID for CICS dump or suppress both.

ACCESS (ACC, LINK)

The ACCESS command allows you to link to third party software programs to display system data. The ACCESS command also allows you to display user-written basic mapping support (BMS) maps and mapsets.

If you want to access information from a third party software package that displays system information with a conversational program, contact BMC Supportfor assistance with linking to this program.

HOGAN, KORE, SMART

Specifies access to the Hogan data group information display.

MAPSETS, MAPSET, MAPS, MAP

Accesses BMS maps via the Map Display Utility.

AFTER (AFT, A)

The AFTER command pauses program execution after the execution of a statement.

For details about location and if-condition, see Variable-and-Common-Parameters.

ON

Sets a breakpoint. 

OFF

Removes the breakpoint.

+offset

Hexadecimal offset within a program. The plus sign (+) is required.

You may set either conditional, unconditional, or multiple breakpoints on a statement.

• 
  
  • Conditional breakpoints are set with an IF clause that provides Code Debug CICS with a selection criterion. Conditional breakpoints halt program execution only if the condition is met. You can only set one conditional breakpoint on a statement.
  • Unconditional breakpoints always halt program execution when they are encountered. No IF clause is used.
  • Multiple breakpoints (after, before, count, or onetime) can be set on one statement. However, if you set a skip on a statement that already contains after, before, count, or onetime breakpoints, SKIP deletes the set breakpoints.

The if-condition is executed according to the following conditions:

• 
  
  • The tests between the first operand and the second operand are made as logical comparisons.
  • Comparisons are made using the length of the first operand or the second operand, whichever is shorter.
  • If the second operand is a numeric value, the data is converted to a format compatible with the first operand unless the second operand is in apostrophes or quotes. Comparisons are made using the length of the first operand.
  • After the statement executes, Code Debug CICS evaluates the first operand and compares its value with the second operand value using the specified operator.
    • If the condition is met, Code Debug CICS takes the breakpoint and halts program execution after the statement executes.
    • If the condition is not met, normal program execution continues, and the breakpoint is not taken.

If an attempt is made to use the AFTER command to set a breakpoint on a COBOL EXIT, GOBACK, or CALL statement, a C return, a PL/I RETURN statement, or an EXEC CICS ABEND, RETURN, or XCTL command, Code Debug CICS will change the after breakpoint to a before breakpoint and issue a message informing the user of the change.

ALLOW

The ALLOW command permits a currently trapped storage violation to take place. Use this command after a potential storage violation is trapped and Code Debug displays a message. Entering either the RESUME or GO command allows the storage violation to occur.

When you enter either a RESUME or a GO command, the system checks to see if the resume location has changed. If it has, the RESUME or GO command is redisplayed with a message to indicate that the ALLOW command has been turned off. Pressing Enter at this point causes the RESUME or GO to execute, causing the next statement to be monitored for storage violations. For more information, see Using-Storage-Protection.

BEFORE (BEF, B)

The BEFORE command pauses execution before the execution of a statement.

For details about location and if-condition, see Variable-and-Common-Parameters.

ON

Sets the breakpoint.

OFF

Removes the breakpoint.

+offset

Hexadecimal offset within a program. The plus sign (+) is required.

You may set either conditional, unconditional, or multiple breakpoints on a statement.

• 
  
  • Conditional breakpoints are set with an IF clause that provides Code Debug CICS with a selection criterion. Conditional breakpoints halt program execution only if the condition is met. You can only set one conditional breakpoint on a statement.
  • Unconditional breakpoints always halt program execution when they are encountered. No IF clause is used.
  • Multiple breakpoints (after, before, count, or onetime) can be set on one statement. However, if you set a skip on a statement that already contains after, before, count, or onetime breakpoints, SKIP deletes the set breakpoints.

The if-condition is executed according to the following conditions:

• 
  
  • The tests between the first operand and the second operand are made as logical comparisons.
  • Comparisons are made using the length of the first operand or the second operand, whichever is shorter.
  • If the second operand is a numeric value, the data is converted to a format compatible with the first operand unless the second operand is in apostrophes or quotes. Comparisons are made using the length of the first operand.
  • Before the statement executes, Code Debug CICS evaluates the first operand and compares its value with the second operand value using the specified operator.
    • If the condition is met, Code Debug CICS takes the breakpoint and halts program execution before the statement executes.
    • If the condition is not met, normal program execution continues, and the breakpoint is not taken.

BOTTOM (BOT)

The BOTTOM command scrolls to the end of the data currently displayed on the screen. Code Debug CICS displays the last available line of data as the second to last line in the data area. An (***END***) indicator appears in the last line of the data area. This command is the same as the DOWN MAX command. For information on the DOWN command, see DOWN (DN). On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the BOTTOM command scrolls the current window. The current window depends on the cursor position when the BOTTOM command is issued. If the cursor is outside of both windows, then the Source window is scrolled.

 CALC (??)

The CALC command is a full-function, COMMAND line decimal/hexadecimal calculator that is available on any screen.

The CALC command can be used to perform any arithmetic operation, including those with parentheses. Literals are treated as hexadecimal unless preceded by a blank.

Any expression may be entered using the following arithmetic and logical operators, evaluated left to right, with the usual precedence:

If an asterisk (*) is used as a prefix operator, it acts as a use contents or indirection operator. For example, entering CALC (*AB000 & 00FFFFFF) + 4 results in the contents of the fullword at address X’AB000’ being logically ANDed with X’00FFFFFF’. The result of this operation is then added to the decimal constant 4. Code Debug CICS then displays the final result in the message field of the screen in decimal, hexadecimal, and character format. For example, if location AB000 contains hexadecimal value F1001234, the result of the above CALC command will be decimal 4664 and hexadecimal 00001238.

CALC parameters need not be separated by spaces. However, if an otherwise valid decimal constant is not preceded by a blank, the CALC command assumes that it is in hexadecimal format. All arithmetic is done in 32-bit binary integers. Addresses default to 32 bits unless an AMODE-24 program is currently at a break or abend. When in doubt, use the logical AND operator to zero out unnecessary data in the high-order byte of an address.

Code Debug CICS also allows the following system and user variables in expressions:

• R0 through R15 denote the contents of program registers. These are only valid when a break/abend is trapped.
• Values CSA, OFL, CWA, TCA, TWA, TUA, PGM, TCT, DCT, EIB, PSW, FCT, TIOA, and COMM are used in the same manner as on the Memory Display screens (2.2 and 9.2). For areas that require a table entry, enter the table name followed by a period and the table entry name (for example, FCT.DBUGEMP).
• User variables defined on the Define User Labels screen (1.9) can be used.
• System variables defined on the Define System Labels screen (9.9) can be used.
• CICS labels used in the various CICS macros and DSECTs may be referenced. However, only the associated offset value is used, not the data at the location in the area presently referenced.
• The special operand (??) may be used in two ways:
  • On the Memory Display screens (2.2 and 9.2) to see the result of the last executed CALC command. Enter ?? in the ADDRESS or OFFSET field to refer to the last CALC command result.
  • With an expression to refer to the saved result of the last executed CALC command. For example, entering CALC ?? +4 will add 4 to the last CALC command result.
• The XDUSERID if-condition keyword can be used. If the SET FOOT DATA command has been issued, the userID CICS associates with the current transaction will be displayed in the footing area of the screen.

If the SET FOOT DATA command has been issued, Code Debug CICS displays the 64 bytes (hex 40) of data at the address pointed to by the last CALC command result. The data is displayed in block hexadecimal format in the footing area of any non-menu screen. This footing can be used to monitor the value of any miscellaneous area. For information on using the SET command to display footing data, see SET.

CANCEL (CAN)

The CANCEL command ends the current Db2 edit session, without saving the data, and returns to the previous screen. Within the Db2 file utility, this command is only available on the DB2 Browse Result Table screen (5.5.4), the DB2 Edit Result Table Row screen (5.5.5), and the DB2 Edit Composite Column screen (5.5.6).

Within the DL/I file utility, the CANCEL command can be used on the Edit DL/1 Segment screen (5.4.4) to roll back any changes made for the currently scheduled PSB.

 CAPTURE (CAP)

The CAPTURE command is used both to start the capture of a script and to end the capture and save the script to a system or user script data set. During the capture process, certain primary commands and corresponding line commands are saved in main storage. This process continues until the script is saved or cancelled, or the debugging session is terminated. To execute a captured script, use the INCLUDE command.

CANCEL

Terminates the current script capture and discards any commands that have been captured.

scriptname

A 1- to 8-character member name used to identify an individual Code Debug script within a system or user script data set. A script name must begin with an alphabetic or national character (A-Z, @, #, and $), and can be made up only of alphanumeric or national characters (A-Z, 0-9, @, #, and $.)

REPLACE

Causes the current script to overwrite any existing script with the same scriptname.

Although screen-specific and transfer commands are not supported, the CAPTURE command fully supports and captures the following primary commands and the equivalent line commands:

• 
  
  • AFTER
  • BEFORE
  • COUNT
  • DELETE
  • INCLUDE
  • KEEP
  • LOAD
  • MOVE
  • ONETIME
  • SET
  • SKIP

Capturing and saving a script is a two-step process. The first step is to capture the commands you issue during your debugging session. Once the commands are captured, you can then either save them to a script data set or discard them.

To begin a capture, simply enter the CAPTURE command. A message will be displayed based on the status of the Script Facility and your current capture mode. If the Script Facility is available and you are not already in capture mode, a CAPTURE STARTED message will be displayed. Continue your debugging session, and as you enter commands eligible for capture, Code Debug will save them in memory.

When you are done capturing your script, enter the primary command CAPTURE OFF scriptname. The script of captured commands will be saved to the system or user script data set specified on the Script Data set Allocation screen (0.6). A message will be displayed if a script with the specified name already exists. You can then either re-enter the CAPTURE OFF command with a different scriptname parameter or replace the existing script by re-entering the command as CAPTURE OFF scriptname REPLACE. To abort an active capture process, enter the CAPTURE CANCEL command. The capture will be terminated, and the commands saved in memory will be discarded.

In addition to using the CAPTURE command, you can manually create or edit a script offline using an editor such as the ISPF editor. A few simple considerations must be observed when manually creating or editing scripts:

• 
  
  • A primary command in a script cannot exceed 120 positions.
  • Only one primary command is allowed per script line.
  • Comment lines can be embedded in a script created or edited offline. A line beginning with an asterisk (*) in column one is a comment line and will not be executed.
  • Only the primary commands listed above should be included in a script.
  • Scripts can be nested, but nesting is limited to seven levels deep. If that limit is exceeded, execution of the script will be terminated.

Example 1:

To capture a script that establishes some breakpoints and keeps you often use when testing program CWDEMCB2, you would enter the following primary commands:

The resulting script, named CWDEMCB2, will be saved in either the system or user script data set, depending on what is specified on the Script Data set Allocation screen (0.6). To establish the same breakpoints and keeps later in that debugging session or in some future session, just type INCLUDE CWDEMCB2 in the COMMAND field and press Enter.

Example 2:

You could capture a script that included the same common breakpoints and keeps and added breakpoints in program CWDEMCB2’s statically linked subprogram CWCDSUBA by entering the following commands:

The resulting script, CWDEMCBA, is saved in whatever script data set is specified on the Script Data set Allocation screen (0.6). To re-establish the same breakpoints and keeps type INCLUDE CWDEMCBA in the COMMAND field and press Enter.

Usage Notes

For the INCLUDE command with a user script name specified to function properly, the Script Data set Allocation screen (0.6) must have the Data set to use field set to U and must specify the correct user script DSN.

 CHAIN (CHN)

The CHAIN command follows a CICS storage chain from the Memory Display screens (2.2 and 9.2). Use this command to specify a hexadecimal value as a parameter that is used as an offset into displayed data in which the chain address is held. The default is 0.

The CHAIN command simplifies the action of tabbing to the HEX OFFSET field, entering a value, tabbing to the USE CONTENTS field, typing in a non-blank value, and pressing Enter. For example, if the current data displayed is a control block that uses offset 4 as a chain to the next block, you would perform the following:

1. Type CHAIN 4 in the COMMAND field to specify offset 4 and press Enter. You would be positioned to the next block in the chain.
2. Type RETRIEVE or simply? — or press the PF key assigned to the RETRIEVE command — to redisplay the entry in the COMMAND fields.
3. Press Enter to execute the CHAIN command.

CHECK

The CHECK command allows you to perform a fast syntax check of SQL data entered on the DB2 Build SQL Easy Query screen (5.5.2).

CLOSE

The CLOSE command closes a currently opened data set or transient data queue. This command is available only from the File Utility screens.

COLS

The COLS command allows you to set or remove a scale line as the first line in the source area of the Source Listing screen (2.L).

ON

Displays the scale line.

OFF

Removes the scale line.

COUNT (COU, C)

The COUNT command gathers information about the flow of execution in your program. When you enter the COUNT command, it sets a counter that is incremented each time the statement executes. At any time during program execution, use the SET FOOT ANALYZE command to display program execution statistics in the footing area of the screen.

 For details about location, see Variable-and-Common-Parameters.

ALL

Sets/removes counts at all executable statements in a program.

When each statement executes, the count is incremented by one. Once the program has finished executing, you may view the results on either the List Breakpoints screen (1.1), or the Source Listing screen (2.L). To reset the count to zero, re-enter the COUNT command.

Using the COUNT command during program execution allows you to:

• 
  
  • Check program efficiency
  • Validate that all logic paths have been tested
  • Help to locate dead code in the program
  • Assist in locating loops.

When you use the COUNT command, you also have the ability to collect data on multiple programs simultaneously:

1. 
   
   1. Change the program name in the MODULE field.
   2. Enter the COUNT command to select the type of count for the new program.
   3. Once the programs execute, enter the name of the program you want in the MODULE field, and the counts will display for that program.

MAX countvalue

Is the equivalent of keying a separate BEFORE breakpoint with the condition “IF COUNT = countvalue”. MAX countvalue is supported for compatibility with Code Debug TSO syntax.

Usage Notes

If you are using the COUNT command with a called subroutine:

• 
  
  • If you are stepping through the main program and reach the subroutine, call in which you have set counts, you must set a breakpoint immediately after the call, and then enter the RESUME command instead of the GO command.
  • You may then continue to step when execution halts after the call.

Examples:

COUNT ALL PARA: Turns count on for all paragraphs within the program.

COUNT ALL EXEC: Turns count on for all EXEC CICS, EXEC DLI, and EXEC SQL statements in the program.

COUNT ALL WA-HOURS: Turns count on for all statements in the program that reference the WA-HOURS data name.

COUNT OFF ALL: Turns count off completely for the program.

COUNT OFF ALL CICS READ: Turns count off for all EXEC CICS READ commands. If count is on for any other type of EXEC CICS command, it will remain set.

COUNT ALL SVC 10: Turns count on for all SVC 10 instructions in the Assembler program.

COUNT ALL: Turns count on for all statements in the program.

CREATE

The CREATE command writes the generated SQL call to the Code Debug CICS SQL transfer data set on the DB2 Browse Generated SQL Call screen (5.5.3).

key-name

Anyone to eight-character name used to save the generated SQL call record in the data set.

If the name already exists, either reissue the CREATE command with a different name, or use the REPLACE command to rewrite the SQL call in the data set. If you use the REPLACE command, the previous SQL call will be overwritten and no longer available.

Use the Code Debug CICS batch SQL utility (DBSQLUTL) to either print the saved call or copy it to another data set for possible inclusion in an application program.

DBOTTOM (DBOT)

The DBOTTOM command scrolls to the end of the data currently displayed on the screen. Code Debug CICS displays the last available line of data as the second to last line in the data area. An (***END***) indicator appears in the last line of the data area. This command is the same as the DOWN MAX command. For information on the DOWN command, see DOWN (DN). On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the DBOTTOM command scrolls the Keep window exclusively, regardless of cursor position.

DDOWN (DDN)

The DDOWN command scrolls forward through the data currently displayed on the screen. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the DDOWN command scrolls the Keep window exclusively, regardless of cursor position.

The DDOWN command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display down so that the line of data on which the cursor is positioned the top line of data. If the cursor is positioned outside of the data area, DDOWN CSR has the same effect as DDOWN PAGE.

HALF

Scrolls the display down n/2 lines, where n is the number of lines of data that can be displayed on a screen.

MAX

Makes the last line of data available the second from the last line displayed. Code Debug CICS displays an indicator in the last line of the data area to show the end or bottom of the data.

PAGE

Scrolls the display down n lines, where n is the number of lines of data that can be displayed on a screen.

nnnn

Scrolls forward through the data for nnnn lines, where nnnn is a decimal value from 1 to 9999.

DELETE (DEL, D)

The DELETE command, available on all screens, removes either a specific object or a data set record, depending on which screen you enter the command. The difference in functionality and command syntax is described separately according to screens:

• All screens
• Source Listing screen (2.L)
• File Utility screens.

All screens:

The DELETE command removes any afters, befores, counts, keeps, runtos, skips, verifys, and whens previously set in a program.

 For details about delete-object, see Variable-and-Common-Parameters.

For example,

removes only the before breakpoints set at all paragraphs in your COBOL program.

Source Listing Screen (2.L)

For details about delete-object, see Variable-and-Common-Parameters.

Use the ALL NX operand on the Source Listing screen (2.L) to delete objects (i.e., counts, keeps, skips, or breakpoints) contained in ALL lines that are not excluded.

The ALL NX operand is a powerful tool when used in conjunction with the SHOW or FIND ALL commands on the Source Listing (2.L) screen. For more information on these commands, see SHOW (SH) and FIND (F).

File Utility Screens

Using the DELETE command on the File Utility screens allows you to delete the currently accessed record from a data set, to delete a temporary storage queue, to delete the currently accessed message from an MQ queue, or to delete a record from an intrapartition transient data queue. Records in extrapartition transient data queues cannot be deleted.

To delete a record from a data set, you must first access the record using the READ command.

DISPLAYP (DP)

The DISPLAYP command ends the current function, and transfers to the Memory Display screen (2.2). From this screen, you can modify memory within a CICS region.

DLEFT

The DLEFT command scrolls the current window to the left. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the DLEFT command scrolls the Keep window exclusively, regardless of cursor position.

On the Memory Display screens (2.2 and 9.2), the DLEFT command functions in the same way as the LEFT and PREV commands. See LEFT (LE) and PREV (PRV).

The DLEFT command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display to the left so that the column in which the cursor is positioned becomes the rightmost column of data displayed. If the cursor is positioned outside of the data area, DLEFT CSR has the same effect as DLEFT PAGE.

HALF

Scrolls the display left half the width of the screen.

MAX

Scrolls the display left to show column 1 as the leftmost column of data.

nnnn

Scrolls the display nnnn columns to the left, where nnnn is a decimal value from 1 to 9999.

PAGE

Scrolls the display left the width of the screen.

DLET

The DLET command issues a DL/I DLET call to delete a segment from a database. It is available only on the Edit DL/1 Segment screen (5.4.4). This command is used when the PSB in use is scheduled via a PCB call.

The DLET command must be preceded by a GHU, GHN, or GHNP call.

 DOWN (DN)

The DOWN command scrolls forward through the data currently displayed on the screen. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the current window depends on the cursor position when the DOWN command is issued.

The DOWN command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display down so that the line of data on which the cursor is positioned the top line of data. If the cursor is positioned outside of the data area,
DOWN CSR has the same effect as DOWN PAGE.

HALF

Scrolls the display down n/2 lines, where n is the number of lines of data that can be displayed on a screen.

MAX

Makes the last line of data available the second from the last line displayed. Code Debug CICS displays an indicator in the last line of the data area to show the end or bottom of the data.

PAGE

Scrolls the display down n lines, where n is the number of lines of data that can be displayed on a screen.

nnnn

Scrolls forward through the data for nnnn lines, where nnnn is a decimal value from 1 to 9999.

DRIGHT

The DRIGHT command scrolls the current window to the right. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the DRIGHT command scrolls the Keep window exclusively, regardless of cursor position.

In the Memory Display screens (2.2 and 9.2), the DRIGHT command functions in the same way as the RIGHT and NEXT commands. See RIGHT (RI) and NEXT (NXT).

The DRIGHT command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display to the right so that the column in which the cursor is positioned becomes the leftmost column of data displayed. If the cursor is positioned outside of the data area, DRIGHT CSR has the same effect as DRIGHT PAGE.

HALF

Scrolls the display right half the width of the screen.

MAX

Scrolls the display right to show the last position of a line of data as the rightmost column of data. MAX is not valid when it is used with DRIGHT or RIGHT to scroll the Keep window.

nnnn

Scrolls the display nnnn columns to the right, where nnnn is a decimal value from 1 to 9999.

PAGE

Scrolls the display right the width of the screen.

DS

DS transfers to the Defined Storage screen (2.3) for Assembler, to the Working Storage screen for COBOL, and to the Variable Storage screen for C and PL/I.

DTOP

The DTOP command scrolls to the start of the data currently displayed on the screen. The first line of data available is displayed as the first line in the data area. This command is the same as the UP MAX command. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the DTOP command scrolls the Keep window exclusively, regardless of cursor position.

DUP

The DUP command scrolls backward through the data currently displayed on the screen. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the DUP command scrolls the Keep window exclusively, regardless of cursor position.

The DUP command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display up so that the line on which the cursor is positioned the bottom line of data. If the cursor is positioned outside of the data area, DUP CSR has the same effect as DUP PAGE.

HALF

Scrolls the display up n/2 lines, where n is the number of lines of data that can be displayed on a screen.

MAX

Displays the first line of data available as the top data line.

nnnn

Scrolls the display up nnnn lines, where nnnn is a decimal value from 1 to 9999.

PAGE

Scrolls the display up n lines, where n is the number of lines of data that can be displayed on a screen.

ELEMENT (ELEM, EL)

The ELEMENT command displays all elementary fields in a program’s variable storage when scrolling and is valid only in HEX ON mode. Use this command on the Program Storage screens (2.3) when viewing data in vertical hexadecimal format for COBOL and PL/I programs only.

END

The END command ends the current Code Debug CICS function and transfers to the next highe-level menu.

File Utility Screens

When accessed from the File Utility screens, the END command takes you back to the previous screen. This occurs only once, however. Using the END command a second time takes you back to the next higher level menu.

Db2 File Utility Screens

When accessed from the Db2 File Utility screens, the END command always returns you to the previous screen.

Code Debug Menus

If you are already at a menu, the END command executes one of the following:

• 
  
  • Transfers you to the next higher-level menu
  • Transfers you from the highest-level menu to the Primary Menu
  • Transfers you from the Primary Menu to the Exit Session screen (X).

EXCLUDE (EXC, EX, X)

The EXCLUDE command excludes specific lines in the source listing being displayed. It is especially powerful when used in conjunction with the FIND command. Use the RESET command to reset the screen display.

For details about find-object, range, direction, and columns, see Variable-and-Common-Parameters.

ALL

Excludes all occurrences of the string or find-object.

Example 1:

Example 1 excludes all lines in the range from the label .HERE through the .THERE label.

The difference between the FIND and EXCLUDE commands is:

• 
  
  • The FIND command changes lines from excluded to non-excluded.
  • The EXCLUDE command changes lines from non-excluded to excluded.
  • The FIND command default is to search all lines.
  • The EXCLUDE command interprets the ALL parameter as a keyword when no search string is specified.
  • The FIND command interprets the ALL parameter as the search string if no other search string is specified.

The following examples show the power of these two commands when used in conjunction:

Example 2:

Example 2 excludes all lines in the program and redisplays only paragraph names in the program.

Example 3:

Example 3 excludes all lines in the program and redisplays the statements where breakpoints have been set. The paragraph or label associated with each of these statements is also redisplayed.

Example 4:

Example 4 excludes all lines in the program and redisplays the statements where the data names for which keeps have been set are defined.

Example 5 excludes all lines in the program and redisplays the statements where the string WA-HOURS is found.

Example 6:

Example 6 excludes all lines in the program and redisplays the line just executed. Subsequent GO 1 commands cause a redisplay of each line executed, enabling the Source Listing screen (2.L) to act in a fashion like the Program Trace screen (2.4).

Example 7:

Example 7 excludes all lines in the program and displays the statements where the string “KEEPS” is found. This example demonstrates the FIND command for the string ’KEEPS’.

The EXEC command ends the current Code Debug CICS function and transfers you to the File Utility Menu. The File Utility allows you to access CICS data sets, temporary storage queues, transient data queues, DL/I databases, Db2 tables, and MQ queues.

EXIT

The EXIT command performs different functions depending on the EXIT_COMMAND_GOES_BACK_TO_CICS global parameter setting and storage protection, trace, and trap settings.

EXIT_COMMAND_GOES_BACK_TO_CICS Global Parameter Set to YES

YES is the default for the EXIT_COMMAND_GOES_BACK_TO_CICS global parameter when Code Debug CICS is shipped. If EXIT_COMMAND_GOES_BACK_TO_CICS is set to YES, the EXIT command clears the screen and returns you directly to CICS. If storage protection, trace, or trap entries are set, the debugging session remains active. If an abend or breakpoint is trapped, the current transaction abends. If no storage protection, trace, or trap entries exist, the debugging session is terminated.

EXIT_COMMAND_GOES_BACK_TO_CICS Global Parameter Set to NO

If the EXIT_COMMAND_GOES_BACK_TO_CICS global parameter is set to NO, the EXIT command ends the current Code Debug CICS function and transfers you to the Exit Session screen (X).

From the Exit Session screen (X) you can end your current Code Debug CICS session or keep it active. You can also produce a transaction abend or a Abend-AID for CICS report.

Once on the Exit Session screen, you can press Enter without making an entry to return you directly to CICS.

FILE

The FILE command ends the current Code Debug CICS function and transfers you to the File Utility Menu. The File Utility allows you to access CICS data sets, temporary storage queues, transient data queues, DL/I databases, Db2 tables, and MQ queues.

 FIND (F)

The FIND command positions to a specified string or area. The command’s syntax depends on the screen that is accessed:

• Memory display screens
• Browse-Container-Data-2-C-3 screen
• File-Utility-Screens
• CSECT-Selections-2-6-2 screen
• Source-Listing-2-L screen
• Task Storage (2.S) screen

Each screen’s syntax is discussed separately.

Memory Display Screens and Browse Container Data Screen

The FIND command syntax for the Memory Display screens and the Browse Container Data screen is as follows:

For details about the direction operand, see Variable-and-Common-Parameters.

* (asterisk)

Code Debug CICS searches for the string specified in the previous FIND command. If a FIND command has not been issued during the session, the * is used as the search string.

Usage Notes

To repeat the search for the string, use the RFIND command. See RFIND (RF). The result of RFIND depends on the values entered in the FIND command:

• 
  
  • If the previous FIND command specified FIRST or NEXT, RFIND repeats the search for the string as if FIND NEXT were used.
  • If the previous FIND command specified LAST or PREV, RFIND repeats the search for the string as if FIND PREV were used.

File Utility Screens

The FIND command syntax for the File Utility screens is as follows:

For details about the direction and columns operands, see Variable-and-Common-Parameters.

* (asterisk)

Code Debug CICS searches for the string specified in the previous FIND command. If a FIND command has not been issued during the session, the * is used as the search string.

Usage Notes

The columns operand is only available on the following screens:

• 
  
  • Browse CICS Data set (5.1.2) (5.1.2)
  • Edit CICS Data set Record (5.1.3)
  • Browse-Temporary-Storage-5-2-2
  • Edit-Queued-Record-5-2-3

To repeat the search for the string, use the RFIND command. See RFIND (RF). The result of RFIND depends on the values entered in the FIND command:

• 
  
  • If the previous FIND command specified FIRST or NEXT, RFIND repeats the search for the string as if FIND NEXT were used.
  • If the previous FIND command specified LAST or PREV, RFIND repeats the search for the string as if FIND PREV were used.

CSECT Selections Screen

The FIND command syntax for the CSECT Selections screen (2.6.2) is as follows:

For details about the direction operand, see Variable-and-Common-Parameters.

Source Listing Screen

The FIND command syntax for the Source Listing screen (2.L) is as follows:

ALL

Finds all occurrences of the string or find-object.

* (asterisk)

Code Debug CICS searches for the string specified in the previous FIND command. If a FIND command has not been issued during the session, the * is used as the search string.

For details about find-object, range, direction, and columns, see Variable-and-Common-Parameters.

Example:

The example finds the first ’A’ in the range of lines from the label .HERE through the .THERE label.

When the find-object parameter is used, the found line becomes the top line of displayed data. When the specified object is a string, Code Debug CICS highlights the string on the display and positions the cursor below the first position of the string. If the object cannot be found, Code Debug CICS redisplays the current data along with an error message.

Usage Notes

To repeat the search for the object, use the RFIND command. See RFIND (RF). The result of RFIND depends on the values entered in the FIND command:

• 
  
  • If the previous FIND command specified FIRST or NEXT, RFIND repeats the search for the object as if FIND NEXT were used.
  • If the previous FIND command specified LAST or PREV, RFIND repeats the search for the object as if FIND PREV were used.

When optional keyword parameters or search boundaries are entered as part of the FIND command, they can be specified in any order and separated by either blanks or commas. Although not normally required, quotes or apostrophes can always be used to enclose the character string that is to be found, avoiding any confusion with the keywords or boundaries. If the FIND command cannot be interpreted, a prompting message is displayed requesting a correction.

Examples:

Variable Storage and Keep Window Displays (2.1, 2.3, and 2.L)

Use the following syntax within the Keep Window sections on the 2.1 and 2.L screens, as well as the 2.3 Variable Storage Screen.

The FIND command works uniquely within the keep window of the Source Listing screen (2.L), the Break/Abend screen (2.1), and on the Program Storage screen (2.3). On the Listing screen (2.L) the Find command functions as described here only when the cursor is positioned within the keep window portion of the screen. When used as described, it only functions within the dataname/variable name area of the keep window (2.L) or data portion of the 2.1 and 2.3 screens.

• 
  
  • When string is used with an Assembler, COBOL, or PL/I program, it is uppercased before comparing. You may enter the string either by itself or may be enclosed within quotation marks (") or apostrophes ('). The leading quotation mark or apostrophe may be preceded by a c, as in character notation, however, at this time, the actual data is always uppercased.
    • Examples: * abc 'abc' "abc" C'abc' C"abc" are equivalent and represent the value ABC.
  • When string is used with a C program, it should always use the C' or C" notation. Using this notation ensures that the string you want to use is not mistakenly uppercased. While you can code a string without using the C' or C" notation, unpredictable results may occur. Examples:
    • C'abc' C"abc" are equivalent and represent the value abc.
    • C'a' and C"a" are equivalent and represent the value a.
    • Specifying a without the C' or C" notation gets uppercased and represents the value A .

If the requested string is found, an informational message is issued, the cursor is positioned on the first character of the found string, and the entire field is highlighted. If the string is not found, a warning message is issued. You can add a parameter (for example, FIRST or LAST) in the FIND command to specify where to start the search and in which direction (forward or backward) to proceed. If no direction parameter is specified, the default NEXT is assumed. This causes the search to start from the current cursor position and continue forward until the string is found or BOTTOM is reached. The FIND command is case-sensitive.

NEXT – Causes the search to start from the current cursor position and search forward until the string is found or BOTTOM is reached.

FIRST – Causes the search to start from the TOP of the storage display and search forward until the string is found or BOTTOM is reached.

LAST – Causes the search to start from the BOTTOM of the storage display and search backward until the string is found or TOP is reached.

PREV – Causes the search to start from the current cursor position and search backward until the string is found or TOP is reached.

The RFIND (Repeat FIND) command reissues the last entered FIND command. The syntax is as follows:

The RFIND command requires no parameters. It is very useful when a FIND PREV or FIND NEXT request reaches TOP or BOTTOM before finding the string and you want to continue searching until the whole table has been searched. The RFIND command, after a FIND FIRST or FIND LAST command, is treated as another FIND NEXT or FIND PREV command, respectively. If no previously saved string is found, an error message is issued.

Processing of the FIND and RFIND commands involves many physical I/O operations and is also CPU-intensive. As the number of datanames in a program increases, the average search time also increases.

Task Storage Display Screen (2.S)

The FIND command syntax for the Task Storage Display screen (2.S) is as follows:

FIRST (FIR)

The FIRST command gets the first message from a queue on the Browse MQ Queue Record screen (5.6.2).

GETPUT

The GETPUT command deletes the currently accessed message from an MQ queue and adds a new message to the queue. This command is available only in the File Utility.

GHN

The GHN command performs a DL/I Get Hold Next call on a database. It is available only on the Edit DL/1 Segment screen (5.4.4). This command is used in the same manner as the GN call, except that it holds the segment open for a possible update by a REPL or DLET call. Use the GHN command only if the program specification block (PSB) in use was scheduled via a PCB call.

The GHN command requests a segment, described by the user-supplied search segment argument (SSAs), that is linked to the preceding call performed on the database. DL/I begins the search at the position where the last call was performed. This position is named the current position in the database. If previous calls have not been performed in the current session and SSAs are not provided, Code Debug CICS retrieves the first segment in the database. If any SSAs are provided and a current position does not exist in the database, Code Debug CICS returns the first segment matching the supplied SSAs.

Code Debug CICS releases the hold on the segment when another DL/I call is made on the database. A REPL or DLET command may not be used for this segment after another DL/I call is made on the database.

GHNP

The GHNP command performs a DL/I Get Hold Next within Parent call on a database. It is available only on the Edit DL/1 Segment screen (5.4.4). GHNP is used in the same manner as the GNP command, except that it holds the segment open for possible update by a REPL or DLET call. Use the GHNP command only if the PSB in use was scheduled via a PCB call.

The GHNP call is similar to a GNP call because it retrieves segments sequentially in a database. Only dependent segments with a given parent segment may be retrieved.

The hold on the segment is released when another DL/I call is made on the database. A REPL or DLET command may not be used for this segment after another DL/I call is made on the database.

GHU

The GHU command issues a DL/I Get Hold Unique call on a database. This command is available only on the Edit DL/1 Segment screen (5.4.4). GHU is used in the same manner as the GU command, except that it holds the segment open for possible update by a REPL or DLET call. Use the GHU command only if the PSB in use was scheduled via a PCB call.

The GHU command is a request for a segment as qualified by the user supplied SSAs. It can be used to access a segment in the database or to establish a position in the database.

The hold on the segment is released when another DL/I call is made on the database. A REPL or DLET command may not be used for this segment after another DL/I call is made on the database.

GN

The GN command performs a DL/I Get Next call on the database. It is available only on the Edit DL/1 Segment screen (5.4.4). Use the GN command only if the PSB in use was scheduled by a PCB call.

The GN command requests a segment, described by the user supplied SSAs, that is linked to the preceding call performed on the database. DL/I begins the search at the position where the last call was performed. This position is named the current position in the database. If previous calls have not been performed in the current session and SSAs are not provided, Code Debug CICS retrieves the first segment in the database. If any SSAs are provided and a current position does not exist in the database, Code Debug CICS returns the first segment matching the supplied SSAs.

When using the GN command, the following tasks occur:

• Processing moves forward from the current position, except if the *F (retrieve first occurrence of this segment) command code is used in the SSA.
• DL/I uses the current position set by the previous call on the database as the starting point for the search.
• The retrieved segment is determined by the next sequential position in the hierarchy of the database and the SSAs used to qualify the call.

To sequentially process through a database, delete all SSAs displayed on the Edit DL/1 Segment screen (5.4.4). Schedule the PSB using the PCB command and repeat the GN command. Sequential retrieval through the database hierarchy is always top to bottom and left to right.

GNP

The GNP command performs a DL/I Get Next within Parent call on a database. It is available only on the Edit DL/1 Segment screen (5.4.4). Use this command only if the PSB in use was scheduled via a PCB call.

The GNP call is similar to a GN call because it retrieves segments sequentially in a database. Only dependent segments with a given parent segment may be retrieved. A GNP call is related to the previous call against the database as follows:

• The search begins at the current position in the database. If no current position exists, it precedes the first root segment in the database.
• The search is limited to the dependents of the lowest segment previously retrieved by a GU or GN call. Parentage limits the end of the search and is in effect only after a successful GU or GN call.
• Parentage is not affected by a GNP call.

GO

The GO command steps through the logic of a program that is currently at a breakpoint, abend, or storage violation trap. GO provides several operands to facilitate program logic checking, and to allow monitoring for data name changes. The OVER operand allows you to step a COBOL PERFORM paragraph statement, stopping at the next executable statement following the PERFORM.

The GO command without any operands specified resumes execution of the program. To single step through a program, you must use the GO 1 command (default PF9 key).

number

Number of statements to be executed. This parameter signals Code Debug CICS that more than one statement will execute before you receive control. Valid entries depend on the value of the delay parameter:

• 
  
  • If the delay value is 0, valid values are from 1 to 5000.
  • If the delay value is greater than 0, valid values are from 1 to 99.

The default values may be changed by the system programmer.

If Code Debug CICS encounters a break/abend while executing GO, it halts execution and returns control to you. When GO is executed from a breakpoint, however, the statement executes but the breakpoint is not retaken.

Examples of the use of the number parameter are:

GO 5: Executes five statements, then returns control to you.

GO 1500: Executes 1500 statements, then returns control to you.

delay

Delay factor that allows each statement to execute slowly, allowing you to observe program execution or changes in data values without pressing a PF key repeatedly. This value may be from 0 (zero) to 20 seconds. A value of 0 specifies that no delay occurs between the execution of successive statements. The maximum value of 20 seconds can be overridden by the system programmer. You can also set a delay interval in a user profile. If a delay-interval is not coded in a profile, the default value shipped with Code Debug CICS is 0.

With a nonzero delay-interval value, Code Debug CICS waits for a specified number of seconds between the execution of each statement in this GO command. The displayed screen is updated at the time indicated by the delay, and each update occurs immediately after execution of one statement.

From the Source Listing screen (2.L), you can watch the logic flow as the program executes at the specified rate. If you have opened the keep window on this screen, you can see the contents of the variables for which you have set keeps or those that participate in the statement about to be executed.

Examples of the use of the number and delay parameters are:

GO 5 0: Executes five statements immediately, without delaying between statements. The screen is refreshed only once. After the fifth statement executes, control is returned to you.

GO 5 5: Executes five statements, delaying 5 seconds between statements. The screen is refreshed after each statement is executed. After the fifth statement executes, control is returned to you.

GO 99 2: Executes 99 statements (the maximum allowed when the delay-interval is non-zero), delaying two seconds between each statement. The screen is refreshed after each statement is executed. After the ninety-ninth statement executes, control is returned to you.

GO 5000 0: Executes 5000 statements (the maximum allowed when the delay-interval is 0), without delaying between statements. This example is the same as entering GO 5000. The screen is refreshed only once after the 5000th statement executes. After the 5000th statement executes, control is returned to you.

TRACE

Executes and traces the next n statements, paragraphs, labeled statements, programs, functions, or procedures.

The TRACE operand allows you to turn Program Trace on temporarily. Program Trace is turned off when stepping is halted. Temporary tracing is accomplished by adding a trace rule for this task and program, with the TRACE option initially set to YES. When stepping is halted, that trace rule is modified to reset the TRACE option to NO.

If another trace rule on the Trace Summary (1.4) screen already includes the task in its tracing criteria, then a temporary trace rule is superfluous; no action is taken.

The trace data will remain available for viewing on the Program Trace (2.4) screen until all trace rules that include this facility are deleted.

UNTIL

Places a condition on the GO command to halt step execution. Before each statement executes in a GO command, Code Debug CICS tests the condition. When it is found to be true, Code Debug CICS halts execution of the program, and you regain control. This parameter is useful in tracking changes in variables or unexplained changes in program logic.

Usage Notes

The UNTIL parameter is executed according to the following conditions:

• 
  
  • If the when-condition is omitted, execution continues until the value of the first operand changes. For example:

is equivalent to

• 
  
  • The tests between the first operand and the second operand are made as logical comparisons.
  • Code Debug CICS makes comparisons using the length of the first operand or the second operand, whichever is shorter.
  • Before the statement executes, Code Debug CICS evaluates the first operand and compares its value with the second operand value using the specified operator.
    • If the condition is met, Code Debug CICS halts execution and you regain control.
    • If the condition is not met, the statement executes, and Code Debug CICS repeats the process until either a break/abend occurs, or execution of the specified number of statements is completed.

The conditions of the UNTIL parameter are only active for the duration of each GO command. Either reenter the conditions for each GO command or repeat them with the REPEAT primary command.

Complete the following procedure to use the GO command most effectively:

1. Set a breakpoint in the program at some point before the location of the problem.
2. Execute the transaction and wait for the breakpoint.
3. Once at the breakpoint, enter the GO command and the condition at which to break.

When the condition is reached, Code Debug CICS returns control to you with a message indicating that the condition was met. If the condition is not met, Code Debug CICS displays a message of the number of statements executed, unless a break/abend occurred or the program terminated.

Examples:

GO 20 UNTIL WA-RATE NE * Executes 20 statements from the current position without waiting between each statement. If the value of WA-RATE changes from its current value, program execution halts after the statement in which the value was changed. This parameter can be abbreviated to GO 20 UNTIL WA-RATE.

GO 50 5 UNTIL WA-RATE EQ 500 Executes 50 statements from the current position, waiting 5 seconds between each statement. If the value of WA-RATE becomes 500, program execution is halted after the statement in which WA-RATE was set to 500.

GO UNTIL R0 = X’00000011’ Executes up to 5000 statements (default num-stmts value when the delay-interval value is 0) or until the contents of register 0 becomes X’00000011’.

GO UNTIL WA-HOURS NE * Executes up to 5000 statements or until the contents of WA-HOURS changes. This parameter can abbreviated as GO UNTIL WA-HOURS.

GO UNTIL WA-HOURS NE 10 Similar to second example, except 10 will be converted to a format compatible with WA-HOURS.

GO UNTIL WA-RATE LT ZERO Program execution halts only if the value of WA-RATE becomes less than 0.

GO UNTIL WA-HOURS NOT NUMERIC Program execution halts only if the value of WA-HOURS becomes non-numeric.

GO 20 TRACE Executes and traces 20 statements from the current location in your program without waiting between each statement, then turns Program Trace off.

GO 5 5 TRACE Executes and traces five statements, waiting five seconds between statements, then turns Program Trace off. Control is returned to you after the fifth statement has been executed.

GO 20 TRACE UNTIL WA-RATE CHANGES Executes and traces 20 statements from the current location in your program without waiting between each statement, then turns Program Trace off. If the value of WA-RATE changes from its current value, program execution is halted at the statement that caused the change and Program Trace is turned off.

Once the GO UNTIL condition is met, program execution halts, and GO UNTIL is redisplayed in the COMMAND field. Normally, pressing Enter causes the GO UNTIL to be reexecuted. However, as the condition is still true, execution does not continue, the breakpoint becomes a before, and the arrow moves to the next statement.

OVER

The OVER operand allows you to step a COBOL PERFORM paragraph statement and stop at the next executable statement following the PERFORM.

This operand is only available if the execution pointer is on a COBOL PERFORM verb that references a COBOL paragraph name. If not, a message will be displayed that the OVER operand is not allowed.

No other operands are valid with this operand.

Examples:

GO OVER Continues execution of the program through the PERFORMed paragraph. Execution will halt when the statement following the PERFORM is reached.

The GOTO command changes the current execution pointer (resume location) of a program that is currently at a breakpoint, abend, or storage violation trap. If the keep window is open, the data values at the current execution point are displayed.

statement

The number of the statement at which to resume execution if source is available for the current program.

+offset

The offset at which to resume execution. This parameter must be a valid hexadecimal number. The plus sign (+) is required.

ADDR address

The address at which to resume execution. The address must be a valid hexadecimal number.

Unlike the GO and RESUME commands, the GOTO command does not resume execution. It only changes the current execution pointer. Use the GO or RESUME command to resume execution from this location.

The GOTO command causes the Source Listing screen (2.L) to relocate to the statement where the current execution pointer has been moved. The resume location displayed on the Break/Abend screen (2.1) and the STATUS footing area reflects the new resume location.

If you are an XPED or XPRT user, the resume location must be within the current program. If you are an XPSP user, a resume location outside of the current program is accepted.

GPREGS

Use the GPREGS command to display the contents of the general-purpose registers in the footer area of the screen.

GROUP

Use the GROUP command on any of the Program Storage screens (2.3) when displaying data in vertical hexadecimal format.

GU

The GU command performs a DL/I Get Unique call on the database. It is available only on the Edit DL/1 Segment screen (5.4.4). This command can only be used when the PSB in use was scheduled via a PCB call.

The GU command requests a segment as qualified by the user supplied SSAs. Use this command to access a segment in the database or to establish a position in the database.

The GU command is the only call that can establish a position backward in a database. Unlike the GN and GNP commands, the GU command does not allow forward movement through a database. DL/I always retrieves the same segment each time the GU call is issued.

HELP (HLP)

The HELP command requests Code Debug’s interactive Help facility. The default is to display help for the current screen.

+

Describes the meaning of messages that are surrounded by plus signs.

ALLOC

Displays dynamic allocation return and reason codes to help with diagnosis of log and script allocation failures.

ATA

Displays information about Code Debug’s Automatic Trap Activation feature.

AUDIT

Displays information about the File, including whether logging is active, the data set to which requests are being logged, and the number and type of requests logged since the most recent activation of the File Utility Audit Trail. FAUDIT is treated the same way as AUDIT.

BREAKS

Displays information about breakpoints.

CHANGES

Displays information about the CHANGES in the current release.

COMMANDS

Displays summary of all primary and line commands.

COV

Displays summary of Code Coverage information.

CUSTINFO

Displays Code Debug CICS customer information including product release and licensed options, licensed CPUs, LMS security release, and license management certificate ID. Code Coverage information is included, if applicable.

DBCTL

Displays current DBCTL status.

DL/I

Displays information about DL/I and I/O commands available.

DL/I-return-code

Displays causes and action information about the DL/I return code.

GLOBAL

Displays the current values of global parameters.

parameter

Limits the display to the value of the parameter specified.

HCI

Displays CICS_ENV parameters found in the CMSC to have a port matching the one specified for the current region.

LEGAL

Displays trade secret notice.

LISTENER

Displays and assists with the configuration of the Code Debug CICS TCP/IP listener.

MESSAGES

Displays log messages and explanations.

MODE

Displays customer information, the transaction used to start Code Debug, and the current operating mode. Also provides a list of available commands when using Diagnosis, Utilities, or Diagnosis/Utilities Mode.

MODULE

Provides product and module information.

MQ

Displays information about the MQ Adapter connection.

MQMD

Displays information about the MQ Message Descriptor.

MQRC

Displays a list of MQ completion codes and reason codes.

NEWS

Displays the new features for this Code Debug CICS release.

NOSOURCE

Displays probable causes to help determine why a source listing cannot be displayed for a program.

OPTimize

Displays the effects of optimization or inline on Code Debug CICS.

PLUS

Describes the meaning of messages that are surrounded by plus signs.

primary-command

A  Code Debug CICS primary command listed in this section.

PROGRAM

Describes MODULE field.

PTFS

Lists currently applied Code Debug CICS and Enterprise Common Components PTFs.

RANGES

Displays information about the RANGE parameter.

RPL

Displays all library data sets in the DFHRPL concatenation.

SCRIPT

Displays either information about the Script Facility or, if a script has been run during the current debugging session, information about the site’s implementation of the Script Facility, the script data set name and run time, and the results of the script execution.

SCROLL

Describes the SCROLL field.

SET

Displays information about Code Debug’s SET primary command.

SLSERR

Displays information about what action to take if a SLS (source level support) error occurs on any source listing screen.

SQLERROR

Displays additional text regarding the current value of the SQL return code.

SQLCODE

Displays information about SQL codes.

SRC

Provides an overview of the Source Listing screen (2.L).

SUBSYSTEM

Displays the status of the Code Debug CICS subsystem.

SUPPORT

Displays information on contacting BMC Support.

SYSINFO

Provides CICS exit information.

SYSTEM

Displays CICS system environmental information. This includes, if applicable, the release number of CICSPlex System Manager in use.

TABLES

Lists CICS Table/Area values.

4038

Displays extended Language Environment information when a user 4038 abend has occurred.

Valid Help Facility Commands

The following commands are valid in the Code Debug CICS Help facility. For your convenience, the default PF key assignments for these commands are also included in this section. Default PF key assignments are those which are shipped with Code Debug CICS. The default PF key for the HELP command is PF1.

BOTTOM

Same as DOWN MAX.

CANCEL

Cancels the current help displays returning back to the original screen from which you entered the Help command.

COLS

Displays a ruler line at the top of each Help screen. Use the COLS OFF to disable the ruler line.

DOWN

Scrolls down by the current scroll amount. Valid only when the SCROLL field is displayed. If you are currently located at the last line of the help screen, the DOWN command skips forward to the next topic. If you are currently located on a help menu, the DOWN command skips forward to the next topic. The default is PF8.

END

Ends returns to the previous help screen. The default is PF3.

FIND

Finds data within the currently displayed Help screen.

HELP

Displays the Help menu. The default is PF1.

MENU

Displays the Help Table of Contents. The default is PF13.

UP

Scrolls up by the current scroll amount. Valid only when the SCROLL field is displayed. If you are currently positioned at the beginning of a help screen, the UP command returns you to the next higher level help menu. If you are currently located on a help menu, the UP command returns you to the next higher level help menu. The default is PF7.

TOP

Same as UP MAX.

HEX (HX)

On the Break/Abend (2.1), Program Storage (2.3), and Source Listing (2.L) screens, the HEX command changes the way data items or working storage data is displayed. In the File Utility, the HEX command changes the way record or segment data is displayed.

HEX ON

Displays the data in vertical hexadecimal format. HEX ON is the default.

HEX DUMP

Displays the data in dump format. HEX DUMP is not available on the 2.1 and 2.L screens.

HEX OFF

Formats the data according to the individual field definitions. In the File Utility, HEX OFF displays data in character format.

HEX VERT

Displays the data in vertical hexadecimal format. VERT is a synonym for ON.

INCLUDE (INC)

The INCLUDE command initiates execution of a previously created script. Primary commands in the script are executed sequentially until the end of the script is detected or an error condition occurs.

scriptname

A 1- to 8-character member name used to identify an individual Code Debug script within a system or user script data set. The DSN and type of script data set must be previously specified on the Script Data set Allocation screen (0.6).

Although screen-specific and transfer command are not supported, the INCLUDE command fully supports and executes scripts containing the following primary commands and the equivalent line commands:

• 
  
  • AFTER
  • BEFORE
  • COUNT
  • DELETE
  • INCLUDE
  • KEEP
  • LOAD
  • MOVE
  • ONETIME
  • SET
  • SKIP

When the INCLUDE command has finished execution, either successfully or unsuccessfully, Code Debug will display a message. The results of the execution are stored in a temporary log and can be viewed with the HELP SCRIPT command.

INSERT (I)

The INSERT command modifies the length of the current I/O area used in the File Utility. The I/O area is used in CICS read/write operations. When Code Debug CICS reads a new record, it automatically acquires a new I/O area and adjusts the length for the current length of the record.

offset

Offset into the current I/O area in which the data is inserted. This parameter may be specified either as a decimal value or a hexadecimal value from 0 to the current size of the I/O area. A leading plus sign specifies a hexadecimal value. This parameter is relative to zero, that is, specifying 0 or +0 inserts the data at the beginning of the I/O area.

If an I/O area does not exist (the record length is zero), only 0 is valid. When the insert takes place, the fill character is replicated for the specified length and inserted in the record beginning at the specified offset. Code Debug CICS shifts all existing data in the record to the right, within the I/O area, so that data is not lost. To add data to the end of the record, specify the current I/O area length displayed as the offset parameter. Data is inserted at the end of the area.

length

Specifies the length of data (number of bytes) that Code Debug CICS can insert into the I/O area. This parameter may be specified either as a decimal value or a hexadecimal value from 1 to the number of bytes remaining until the maximum record size is reached. A leading plus sign specifies a hexadecimal value.

fill

Specifies the fill character that Code Debug CICS uses when inserting data into the I/O area. This parameter specifies a one-byte value that is used to initialize the data in the record. Two types of fill characters are allowed:

• 
  
  • Single-character value enclosed in single or double quotes
  • Two-position hexadecimal value enclosed in single or double quotes with a leading X (for example, X'C1').

The default fill-character value is X’00’ (binary zeros).

If you access a display/update screen, an I/O area may not be acquired yet (the record length field will be 0). In this case, enter the INSERT command without parameters. An I/O area the size of the maximum allowed record length is automatically acquired and initialized to binary zeroes. However, parameters can also be coded to acquire an I/O of a different length and fill character.

Example 1:

Example 1 inserts 80 bytes of binary zeroes in front of the current I/O area.

Example 2:

Example 2 inserts 80 bytes of the letter A into the I/O area beginning at offset 64 (X’40’). Bytes 0 through 63 remain unchanged. Bytes 64 through 143 now contain the letter A (X’C1’). Bytes 144 through the end of the I/O area contain the data that previously began at offset 64 in the I/O area.

Example 3:

Example 3 inserts 80 bytes of binary zeroes beginning at offset 64 (X’40’) into the I/O area. Bytes 0 through 63 remain unchanged. Bytes 64 through 143 contain binary zeroes (the default fill character). Bytes 144 to the end of the I/O area contain the data that previously began at offset 64 in the I/O area.

Example 4:

Example 4 inserts 12 bytes of binary zeroes beginning at offset 64 (X’40’) into the I/O area. Bytes 0 through 63 remain unchanged. Bytes 64 through 75 contain binary zeroes (the default fill character). Bytes 76 through the end of the I/O area contain the data that previously began at offset 64 in the I/O area.

Example 5:

Example 5 inserts 80 bytes of binary zeroes beginning at offset 64 (X’40’) into the I/O area. Bytes 0 through 63 remain unchanged. Bytes 64 through 143 contain binary zeroes (the default fill character). Bytes 144 to the end of the I/O area contain the data that previously began at offset 64 in the I/O area.

INTERCEPT

The INTERCEPT command is used to load the program or a statically linked subroutine within the program, then set a before breakpoint at the entry-point of the specified program or subroutine.

The parameter descriptions for the INTERCEPT command are:

program-name

The name of the load module. A value is required for this field. The value can be any valid program name not exceeding eight characters.

subroutine-name

The name of the statically linked subroutine to be tested. The value cannot exceed eight characters. When this format of the command is used, the breakpoint is set at the start of this subroutine and the subroutine is selected for debugging.

LOAdm

To test a statically linked subroutine within a load module, enter the name of the composite load module as the value for program-name.

ISRT

The ISRT command performs a DL/I ISRT call on a database to insert a segment. It is available only on the Edit DL/1 Segment screen (5.4.4). This command can only be used when the PSB in use was scheduled via a PCB call.

Before entering an ISRT command, build the new segment in the I/O area. If an I/O area does not currently exist, use the INSERT command to create one. The fields of the new segment in the I/O area must have the same order and length as defined for the segment.

When inserting a root segment, DL/I places it in the correct sequence in the database using the key fields supplied in the I/O area. When the inserted segment is not a root, but its parent was just inserted, use the ISRT command with an unqualified SSA to insert the child segment. An unqualified SSA may also be used to insert a root segment.

Add new segments directly or sequentially after building them in the I/O area. At least one SSA is required; the last or only SSA must specify the new segment. If the new segment contains a unique key field, Code Debug CICS uses the key to determine where the segment is inserted into the database. If a unique key field does not exist for the segment, the insert rules defined by the site’s database administrator during the DBD generation are used.

 KEEP (K)

The KEEP command turns on or off data-name keeps for variables in Assembler, C, COBOL, and PL/I programs. Keeps allow you to display and modify the current contents of variables during program execution.

Array variables default to displaying the first occurrence in the keep window. The occurrence number can be modified in the keep window to view other occurrences of the variable.

The Code Debug CICS 2.L screen and the variable display portion of the 2.1 and 2.3 screens contain a helpful feature that continuously displays the next occurrence of a table element each time you press Enter. Appending a signed integer (-1 or +1, for example) to any disassociated occurrence level number causes Code Debug CICS to repeatedly increment or decrement the subscript by the specified amount.

For example, if the current occurrence number is:

and you append +1, like this:

Code Debug CICS displays occurrence 3,4,6. The occurrence field now displays:

When you press Enter again, occurrence 3,4,7+1 is displayed and so on. This technique can be applied at any level and at more than one level at a time. This means that

and other combinations of this type are permitted.

When a break/abend occurs, you can display the current contents of variables on the Source Listing screen (2.L), Break/Abend screen (2.1), or Program Storage screens (2.3).

Code Debug CICS supports setting the KEEP command on 88 level fields in COBOL programs. Setting a keep on an 88 level field also sets a keep on the associated parent field. Deleting a keep from an 88 level field will leave the keep on the parent field, but deleting the keep from the parent field will also delete the keep from any associated 88 level fields.

The KEEP command is allowed only for programs that have been compiled using the BMC language processors. This command only works with the data labels described in Variable-and-Common-Parameters and statements that define data fields with a label.

ON

Adds the specified variable name to the list of keeps that display for this program when a break/abend occurs. The default is ON.

OFF

Removes a keep that has been set for this variable name from the program’s keep list.

ALL

Indicates that all keeps for the current program should be deleted. ALL is valid only in combination with OFF.

The KEYS command temporarily displays the PRIMARY PF KEY SETTINGS (0.2) screen that is used to modify the current PF key settings.

The PRIMARY PF KEY SETTINGS screen has two fields for each PF key:

VALUE: Command data substituted into the COMMAND field when the PF key is pressed.

LABEL: Eight-character label for the PF key that displays on the footing if the SET FOOT KEYS command has been entered. If the label field is left blank, Code Debug CICS displays the first eight characters of the PF key value.

After modifying key values, use the END command to return to the previous screen, or press Enter to view and modify the alternate PF keys PF13 - PF24.

Note that when a PF key is pressed, the value on the COMMAND field is appended to the current value of the PF key. For example, typing the number 10 in the COMMAND field and pressing the GO PF key is the same as a GO 10 command.

If a user has specified a profile name for the session, any changes in PF key values are stored and remain in effect in following sessions.

LEFT (LE)

The LEFT command scrolls the current window to the left. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the current window depends on the cursor position when the LEFT command is issued.

On the Memory Display screens (2.2 and 9.2), the LEFT command and the PF key assigned to the LEFT command function in the same way as the PREV command. See PREV (PRV). By the same token, the RIGHT command functions in the same way as the NEXT command. See NEXT (NXT).

The LEFT command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display to the left so that the column in which the cursor is positioned becomes the rightmost column of data displayed. If the cursor is positioned outside of the data area, LEFT CSR has the same effect as LEFT PAGE.

HALF

Scrolls the display left half the width of the screen.

MAX

Scrolls the display left to show column 1 as the leftmost column of data.

nnnn

Scrolls the display nnnn columns to the left, where nnnn is a decimal value from 1 to 9999.

PAGE

Scrolls the display left the width of the screen.

LIBRARY (LIB)

Use the LIBRARY command from any screen to display information about the current program entered in the MODULE field. The LIBRARY command includes information such as load library information and source listing data set information and provides the same information as the HELP MODULE command.

The following table  lists the information sections of the LIBRARY command. Use the UP/DOWN commands to scroll through the display. Use the END command to return to where the LIBRARY command was originally issued.

LIBRARY Information Sections

LOAD

The LOAD command allows you to load a program just as though you had typed the program name in the MODULE field of a Code Debug CICS screen. You can also select an individual CSECT within the specified load module.

When the Script Facility is performing a capture, if you enter a program name in the MODULE field, Code Debug will generate an equivalent LOAD command in the script being captured.

Example 1

Example 1 loads the load module for program CWDEMCB2.

Example 2

Example 2 loads the load module for program CWDEMCB2 and selects the CSECT CWCDSUBA.

LOCATE (LOC, L)

The LOCATE command positions to an area in the data currently displayed on the screen. This command is available in the following screens:

• Source Listing (2.L)
• Program Storage (2.3)
• File Utility (5)
• List of CSECTs (2.6.1)
• List of DLL Functions (2.6.F)
• Program Channel Display (2.C.1)
• Channel Container Display (2.C.2)
• Task Storage (2.S)
• Load Profile (0.4)

The command’s syntax depends on the screen that is accessed.

Global Command

The LOCATE * global primary command allows the user to transfer from any screen within Code Debug (except a menu) directly to the Source Listing screen (2.L) or Assembler Break/Abend screen (2.20). The LOCATE * command is supported for Assembler, C, COBOL, and PL/I. It provides an easy-to-use command for repositioning to the Source Listing screen.

Usage Notes

The LOCATE * global primary command executes according to the following processing rules:

• 
  
  • If the current debugging session is not in a break/abend state:
    • If no program name is currently displayed in the MODULE field, Code Debug CICS will transfer to the Source Listing screen (2.L), and the message PROGRAM NAME IS REQUIRED will be displayed.
    • If a program name is currently displayed in the MODULE field, but no source exists for the program, Code Debug CICS will transfer to the Source Listing screen (2.L), and the message NO SOURCE AVAILABLE will be displayed.
    • If a program name is currently displayed in the MODULE field and source exists for the program, Code Debug CICS will transfer to the Source Listing screen (2.L), and the listing will be positioned to the first executable statement in the program.
  • If the current debugging session is in a break/abend state:
    • The MODULE field will be examined and updated as follows:
      • If the program name displayed in the MODULE field is not the program currently at a breakpoint or abend, or the MODULE field is blank, the name of the program that is currently at a breakpoint or abend will be displayed in the MODULE field.
      • If the program name displayed in the MODULE field is the program currently at a breakpoint or abend, the MODULE field will remain unchanged.
    • After the MODULE field has been examined and updated, one of the following will occur:
      • If no source exists for the program name displayed in the MODULE field, Code Debug CICS will transfer to the Assembler Break/Abend screen (2.20).
      • If source exists for the program name displayed in the MODULE field, Code Debug CICS will transfer to the Source-Listing-2-L screen, and the listing will be positioned to the current execution pointer.

Source Listing Screen

The LOCATE command is used to position quickly to a line in the source listing. This command differs from the FIND command because it positions to a unique area within a source listing by using internal indexes, which allow quick and efficient positioning. The FIND command, on the other hand, positions to multiple occurrences of a string within a source listing by interrogating each line of the listing while looking for the given string. The LOCATE command requires entering the entire data name or paragraph, while FIND allows locating partial strings.

Use the LOCATE command on the Source-Listing-2-L screen to:

• 
  
  • Locate the current execution point by omitting the parameter
  • Locate the current execution point with ABEND parameter
  • Locate a decimal statement number
  • Locate a hexadecimal offset
  • Locate an area in a program
  • Locate a paragraph (label) in a program
  • Locate a line where a variable is defined
  • Locate to a symbolic label.

Each of these uses of the LOCATE command is described separately.

Locate by Omitting the Parameter

If currently at a break/abend, enter LOCATE without a parameter to position the line where the break/abend occurred near the top of the source display portion of the screen. If not at a break/abend, Code Debug CICS positions the first executable statement or instruction in the program at the top of the source display.

Locate with the STOP or ABEND Parameters

If currently at a break or abend state, LOCATE STOP or LOCATE ABEND positions the line where the break/abend occurs at the top of the source display portion of the screen. If not currently at a break or abend state, LOCATE STOP or LOCATE ABEND cause an error message to be displayed, and the listing is not repositioned.

Locate a Decimal Statement Number

The line corresponding to the specified statement number displays as the first line in the source display. However, if the specified statement number is before the first statement in the program, Code Debug CICS displays the first statement. If the statement number is greater than the last statement in the program, Code Debug CICS displays the last statement.

Examples of this use of the LOCATE command are:

LOCATE 0: Positions the display at the first statement in the program.

LOCATE 255: Positions the display at statement 255 in the program.

LOCATE 999999: Positions the display at the last statement in the program.

Locate a Hexadecimal Offset

Enter a hexadecimal offset preceded by a plus sign (+). The line corresponding to that offset in the program displays as the first line in the source display portion of the screen. However, if the specified offset is before the first executable instruction in the program, Code Debug CICS displays the line corresponding to the first executable instruction. If the offset is greater than the last executable instruction in the program, Code Debug CICS displays the line corresponding to the last executable instruction.

Examples of this use of the LOCATE command are:

LOCATE +0: Positions at the first executable instruction in the program.

LOCATE +AD2: Positions at the executable instruction associated with offset X’AD2’.

LOCATE +FFFFE: Positions at the last executable instruction in the program.

This method positions the display to the section in the listing associated with the keyword.

Enter a listing-section parameter from the keyword list in the following table The parameter positions the display based on one of two options:

TOP: Positions at the start of the section. The default is TOP.

BOTTOM (BOT): Positions at the end of the section.

LOCATE Listing-Section Parameter Keywords

Examples of this use of the LOCATE command are:

LOCATE WS: Positions at the first line in the working storage section of the program.

LOCATE WS BOTTOM or L BOT WS: Positions at the last line in the working storage section of the program, which becomes the bottom line of the display.

L PROC: Positions at the first line in the procedure division of the program.

Locate a Label in a Program

To locate a paragraph in a COBOL listing or a label in an Assembler or PL/I program, use PARAGRAPH and paragraph-name parameters.

PARAGRAPH (PARA): Specifies a particular paragraph name in a COBOL program or a label in a PL/I or Assembler program.

paragraph-name: Set of one or more COBOL sentences making up a logical processing entity and preceded by a paragraph name or a paragraph header. This can also refer to a label in the executable part of an Assembler or PL/I program.

Locate a Line Where a Variable is Defined

To locate a line where a COBOL variable, PL/I variable, C variable, or Assembler label is defined, use the DATANAME and variable parameters.

1. 
   
   1. Keyword list for the matching keyword.
   2. Procedure cross-reference for the procedure name.
   3. Variable cross-reference for the variable.

For example, if LOCATE ABC is entered, Code Debug CICS first determines if ABC matches the list of area keywords. If a match is found, that area is displayed. If a match with the area keywords is not found, Code Debug CICS searches for a paragraph or label ABC defined in the program; if found, it is displayed. If a match in the procedure cross-reference is not found, Code Debug CICS then searches the variable cross-reference and displays it if found. If no matches are found, the UNABLE TO LOCATE error message is displayed.

Locate to a Symbolic Label

To locate where the symbolic label is defined, use the symbolic label parameter. Symbolic labels are defined in the line command field of the Source Listing screen (2.L). For example, LOC .HERE positions to the line where the .HERE symbolic label was previously defined.

Source Listing and Break/Abend Screens — Keep Window

The LOCATE command positions to the variable in the keep window of the Break/Abend screen (2.1) and is valid in formatted, vertical hex, and dump display modes. If the cursor is in the Keep window of the Source Listing screen (2.L), it will also position to the variable in the Keep window. If the cursor is in the Command line or listing area, it will position to the variable in the source area of the screen.

Working Storage Screen for COBOL Programs

The following syntax lists the parameters necessary to locate a particular section or data name in working storage. This syntax is valid only on the Working Storage screen (2.3) when in a break/abend state.

WS

Positions the current display to the beginning of working storage. This command is valid:

• 
  
  • 
    
    • for COBOL programs only
    • on the Working Storage screen (2.3) or the Source Listing screen (2.L)
    • in all display modes.

TWA

Positions the current display to the beginning of the Terminal Work Area (TWA). This command is valid:

• 
  
  • 
    
    • for COBOL programs only
    • on the Working Storage screen (2.3)
    • for dump display mode only.

EIB

Positions the display to the beginning of the Execute Interface Block (EIB). This command is valid:

• 
  
  • 
    
    • for COBOL and PL/I programs
    • on the Data Area screens (2.3) only
    • in the following display modes:
      • formatted
      • vertical hex (only if DFHEIBLK is defined within the program)
      • dump (only if DFHEIBLK is defined within the program)

COMM

Positions the current display at the beginning of the CICS communication area (COMMAREA). This command is valid:

• 
  
  • 
    
    • for COBOL programs only
    • on the Working Storage screen (2.3)
    • in dump display mode.

locator-cell

Positions the current display at the beginning of the storage pointed to by a COBOL locator cell.

The format of a locator cell is:

Where cell may be one of the following:

Where nnn may be a 1 to 3 digit cell number.

This command is valid:

• 
  
  • 
    
    • For COBOL programs only
    • On the Working Storage screen (2.3)
    • In the following display modes:
      • formatted
      • vertical hex
      • dump.

Enter a data-label name or partial name followed by an asterisk to position to the first occurrence of the string in the keep window if the requested string is found. If the requested string is not found, a warning message saying the requested string is not found is issued.

Variable Storage Screen for PL/I Programs

Locates to a particular section of PL/I variable storage or data name in variable storage only when the program is in a break/abend state on the Variable Storage screen (2.3).

Enter a data-label name or partial name followed by an asterisk to position to the first occurrence of the string in the keep window if the requested string is found. If the requested string is not found, a warning message saying the requested string is not found is issued.

Use the following LOCATE command syntax to locate to a particular data label in an Assembler program. It can only be used when in a break/abend state on the Defined Storage screen (2.3), or in the keep window of the Break/Abend (2.1) and Source Listing (2.L) screens.

Enter a data-label name or partial name followed by an asterisk to position to the first occurrence of the string in the keep window if the requested string is found. If the requested string is not found, a warning message saying the requested string is not found is issued.

Variable Storage Screen for C Programs

Use the following LOCATE command syntax to locate to a particular section of the C variable storage. It can only be used when in a break/abend state on the Variable Storage screen (2.3), or in the keep window of the Break/Abend (2.1) and Source Listing (2.L) screens.

Enter a variable name to position to the definition of the variable within the variable storage map. Variables may need to be fully qualified, so they position to the correct occurrence. The PARAMETERS and LOCALS operands may be entered with a Function name to position to the appropriate section of the variable storage map.

List of CSECTs Screen

The LOCATE command is used to position quickly to a specific CSECT within the list.

CSECT-name

Locates a specific CSECT within the list.

List of DLL Functions Screen

The LOCATE command is used to position quickly to a specific function within the list.

function

Locates a specific function within the list.

Program Channel Display Screen

The LOCATE command is used to move a specific channel to the top of the screen.

function

Moves a specific channel to the top of the screen.

The LOCATE command is used to move a specific container to the top of the screen.

function

Moves a specific container to the top of the screen.

Task Storage Screen

The LOCATE command is used to position quickly to a specific area within the list which contains that address within its boundaries.

storage-address

Locates a specific storage area.

File Utility List Screens

The LOCATE command is used in the following File Utility List Screens:

• 
  
  • CICS Data set List (5.1.1)
  • Temporary Storage Queue List (5.2.1)
  • Transient Data Queue List (5.3.1)
  • DL/I PSB List (5.4.1)
  • DL/I PCB List (5.4.2)
  • DL/I Segment List (5.4.3)
  • DB2 Table/View List (5.5.1)
  • DB2 Build SQL Easy Query (5.5.2)
  • DB2 Browse Result Table (5.5.4)
  • DB2 Edit Result Table Row (5.5.5)
  • DB2 Edit Composite Column (5.5.6)
  • MQ Queue List (5.6.1)

The syntax of the LOCATE command on these screens is as follows:

file-resource

Storage area that can be defined in CICS, such as queues or files. Valid types vary depending on the screen from which the LOCATE command is entered:

• 
  
  • 
    
    • 5.1.1 Screen: Data set
    • 5.2.1 Screen: Temporary storage queue
    • 5.3.1 Screen: Transient data queue
    • 5.4.1 Screen: PSB
    • 5.4.2 Screen: PCB
    • 5.4.3 Screen: Segment
    • 5.5.1 Screen: Creator/table
    • 5.5.2 Screen: Column name
    • 5.5.4 Screen: Column name/number
    • 5.5.5 Screen: Column name
    • 5.6.1 Screen: MQ Queue

File Utility Display Screens

The LOCATE command is used in the following File Utility Display screens:

• 
  
  • Edit CICS Data set Record (5.1.3)
  • Edit Queued Record (5.2.3)
  • Edit Transient Data Queue Record (5.3.2)
  • Edit DL/1 Segment (5.4.4)
  • DB2 Edit Composite Column (5.5.6).

The syntax for the LOCATE command on these screens is as follows:

variable

Positions the display at the specified data name. This parameter is available only when a record has been mapped with the USING command. For more information, see USING.

The types of variables that can be subscripted are:

• 
  
  • 
    
    • Arrays (PL/I)
    • Tables (COBOL)
    • Labels with a duplication factor greater than 1 (Assembler).

bound

Acts as a subscript to specify the occurrence of the variable for a given level. The number of bounds and their values are checked against the current bounds for a variable to ensure the correct number of bounds and that the value of the bound matches. The number of bounds for each variable is restricted by the language of the application program. They must be numeric.

If a bound is used, the bound values will be used as the occurrence of the variable when displayed. If the array has multiple bounds, but you wish to change only the first few, you need only enter the bounds that you wish to change and erase the remaining bounds. The unmodified bounds will default to the first element.

In a multi-dimensional array, if a selection is made at a higher logical level, the selection is propagated to all levels directly below this entry, that is, to all levels logically subordinate to this level.

Load Profile Screen

The LOCATE command is used to position quickly to a specific NAME within the list of profile names. Full or partial (leading position) profile names can be used.

Profile

Locates a specific profile name within the list.

LOCK

The LOCK command is used on the Memory Display (2.2 and 9.2) screens or the Select Address screen to lock the current address in the address table so it will not be deleted. The table holds sixteen entries; when the table is full, the oldest unlocked entry is automatically deleted to allow for the next entry. Locking an entry prevents it from being deleted when a new entry is added. If 16 entries are locked, no new entries are added to the table. See SELECT (SEL).

label

Assigns a label to the entry being locked. Labels can be no longer than eight characters, can be alphanumeric, and must be unique. If a duplicate label is entered, an error message is issued and the command is redisplayed.

MEMORY

The MEMORY command ends the current Code Debug CICS function and transfers to the Memory Display screen (2.2). From the Memory Display screen, you can modify memory allocated to your task.

MENU (MEN)

The MENU command ends the current Code Debug CICS function and transfers to the Primary Menu.

When using the Help facility, the MENU command transfers you to the highest-level Help menu.

MONITOR

The MONITOR and REVERSE commands are used to activate review mode. Review mode enables you to record and then review the execution path by reversing the direction of program execution. When review mode is active, the direction in which the current review is processing, Forward or Reverse, will be displayed on the execution status line.

Use the MONITOR command before executing your program to record execution. Then use the REVERSE command to review the execution history by tracing through the recorded history in the reverse direction. You can see the execution path and the changing data values as you review program execution.

MONITOR records the program’s execution in containers.

Usage Notes

• 
  
  • Use the DELETE MONITOR command to stop recording the execution history.
  • The REVERSE and RESUME commands are valid only if MONITOR has first been turned on.
  • If MONITOR is turned on, MNTR will be displayed in the first header line. You can also use the MONITOR Summary screen (1.M) to view the status of the MONITOR function.

MOVE

The MOVE command allows you to modify the contents of program variables. It has the same rules and behavior as the COBOL MOVE verb.

data

A data item or variable defined in the current program. The source of the data being moved is data-1, and the target of the move is data-2. This parameter can be substringed to move only specific bytes as shown in the following examples.

literal

The literal to be moved can be any of the following:

• 
  
  • signed or unsigned integer
  • floating point number
  • alphanumeric string enclosed in single or double quotes, such as 'CURRPAY' or "WRKHOUR".
  • hexadecimal string enclosed in single quotes, such as x’A7978584’
  • bit string enclosed in single quotes, such as b'101' (PL/I only)
  • figurative constant, such as spaces, zeros, high-values, or low-values.

TO

Required keyword separating the data-1 or literal value from data-2.

Usage Notes

• 
  
  • When the Script Facility is performing a capture, if you overtype a value displayed with the PEEK or KEEP command, Code Debug will generate an equivalent MOVE command in the script being captured.
  • A MOVE command cannot be longer than 120-character positions.
  • No validation is performed on hexadecimal strings other than to verify that they contain valid hex digits.
  • All moves except hexadecimal strings are subject to COBOL compatibility rules. A message will be displayed if those rules are violated. The message will include a matrix of compatibility rules.
  • If an attempt is made to move a non-numeric data type into a numeric field, the data will be validated. If the data contains only numeric characters, it will be converted to the same data type as the receiving field. If the data contains other non-numeric characters, a message will be displayed indicating whether it was moved.
  • If specific decimal formatting is desired in the receiving field, a decimal point must be provided in the literal value.
  • Floating point literal input is essentially “free-form”. Non-numeric characters—such as E, e, plus (+), minus (-), and the decimal indicators comma (,) and period (.)—in floating point literals are optional if the desired value can be determined without them. For example, the values 5, +5, 5.0, +5.0, 5e1, +5E1, and +5.0E+01 all generate the same internal value.
  • Moves to COMP-1 or COMP-2 fields from COMP (binary) and COMP-3 (packed decimal) fields are supported. Moves from COMP-1 or COMP-2 fields to COMP or COMP-3 fields are not supported.

The following examples show uses of the MOVE command:

Example 1

Example 1 moves a value from one program variable to another.

Example 2

Example 2 moves zeros to a numeric program variable.

Example 3

Example 3 moves a hex value to a program variable.

Example 4

Example 4 demonstrates the use of displacement and length on the data-2 parameter. This overlays the LASTNAME field starting at the second character for a length of eight.

Example 5

Example 5 moves a value to a program variable defined as an array. “STRATTON” is moved to the second element of the array field LASTNAME-ARRAY.

Example 6

Example 6 demonstrates the use of displacement and length with the same array program variable used in Example 5. “AFFORD” is moved to the second element of the array field LASTNAME-ARRAY and overlays it starting at the third character for a length of six. Combined with the move in Example 5, this creates the literal “STAFFORD.”

Example 7

Example 7 moves zeros to a floating point program variable.

Example 8

Example 8 demonstrates how to move a value from one numeric program variable to a floating point program variable.

Example 9

Example 9 moves a specific value to a floating point program variable. The plus (+) symbols and the exponent are optional. If either the value or the exponent is negative, minus (-) symbols and the exponent are required.

 NEXT (NXT)

The NEXT command scrolls to the next area in the data currently displayed on the screen. The functionality of this command depends on the screen from which it is accessed:

• File Utility screens
• Memory Display screens (2.2 and 9.2).

Each is discussed separately.

File Utility Screens

The NEXT command reads the next record from the currently accessed data set, temporary storage queue, transient data queue (input only), or MQ queue. For data sets, the BROWSE option must be specified in the file resource definition.

This command is the same as the READ NEXT command in the File Utility.

Memory Display Screens

The NEXT command displays data by using the next address from the address table used in the Memory Display screens (2.2 and 9.2). Each time a new address is displayed on a Memory Display screen, Code Debug CICS records the address in a table.

The NEXT command redisplays the address from the next entry in the table. Each time the NEXT command is used, the next entry in the table becomes the current entry. You can use the NEXT command in conjunction with the PREV command to reposition to entries within this table.

The RIGHT command performs the same function as the NEXT command on the Memory Display screens (2.2 and 9.2).

The LEFT command performs the same function as the PREV command on the Memory Display screens (2.2 and 9.2).

ONETIME

The ONETIME command sets a temporary breakpoint on a statement. The onetime breakpoint pauses execution before the statement and is then automatically deleted.

For details about location, see Variable-and-Common-Parameters.

ON

Sets the breakpoint.

OFF

Removes the breakpoint.

0

Set the breakpoint before the first statement in the program. 0 is the default.

CSR

The CSR option is only valid on the Source Listing screen (2.L).

If the cursor is located within the listing window of the 2.L screen when the command is entered, a onetime breakpoint will be generated as though the O line command had been entered on that line. If the cursor is not located within the listing section, the ONETIME CSR command is not valid and will result in an error message.

+offset

Hexadecimal offset within a program. The plus sign (+) is required.

You may set multiple breakpoints on a statement.

• 
  
  • Multiple breakpoints (after, onetime, or count) can be set on one statement. However, if you set a skip on a statement that already contains after, count, or onetime breakpoints, SKIP deletes the set breakpoints.

Before breakpoints take precedence over onetime breakpoints. If a before already exists, the onetime cannot be set.

OPEN

The OPEN command opens a currently closed data set or transient data queue. This command is only available in the File Utility on the Edit CICS Data set Record screen (5.1.3) and the Edit Transient Data Queue Record screen (5.3.2).

PCB

The PCB command schedules a DL/I PSB for processing. It is available only on the Edit DL/1 Segment screen (5.4.4). This command can be used only if authorized by your system programmer via the Code Debug CICS global parameter FILE_UTILITY_DLI_ENABLE_PCB_TERM_CALLS.

The PCB command schedules the PSB and holds it open for use on the Edit DL/1 Segment screen (5.4.4). The PSB remains scheduled until a TERM call (TERM command) is used to terminate the PSB, the PSB time-out limit is exceeded (default is 2 minutes), the END command is used to transfer off the screen, or the CANCEL command is used to roll back changes in progress. The PSB time-out limit is set by the Code Debug CICS global parameter FILE_UTILITY_DLI_PSB_SCHEDULE_MAX. This prevents a PSB from unintentionally locking out access to a DL/I database if a terminal is left active while on the 5.4.4 screen.

If processing to a database takes place (that is, a DL/I call is performed while a PSB is scheduled), Code Debug CICS resets the time-out counter to a full 2 minutes. If no DL/I calls are performed on the PSB within the time-out limit, Code Debug CICS automatically terminates the PSB, rolling back any changes in progress, and displays a message. If the PSB is not terminated before leaving the 5.4.4 screen, Code Debug CICS automatically terminates the PSB and rolls back any changes in progress when leaving the 5.4.4 screen.

If a PSB is currently scheduled, Code Debug CICS displays the message PSB IS SCHEDULED to the right of the RECFM field on the screen. If a PSB is not scheduled, the PSB IS NOT SCHEDULED message is displayed.

PEEK (P)

The PEEK command, when entered with a variable as the parameter, transfers to the Program Storage screen (2.3) and positions the display so the variable is displayed at the top of the screen. This allows the value of the variable to be displayed and edited.

If the reserved-labels PSW or Rn (register) are entered as the parameter, no transfer will occur. Instead, the command will function identically to the CALC command, with the value of the PSW or register being displayed in the message area of the screen.

This command is only valid while in a break/abend state.

PFSHOW

The PFSHOW command is used to display or hide the current PF key settings. Enter PFSHOW or PFSHOW ON to display the current PF key settings. This is equivalent to entering SET FOOT KEYS. Enter PFSHOW OFF to hide the current PF key settings. This is equivalent to entering SET FOOT OFF.

 PREV (PRV)

The PREV command scrolls to the previous area in the data currently displayed on the screen. The command’s function depends on the screen that is accessed:

• File Utility screens
• Memory Display screens (2.2 and 9.2).

Each is described separately.

File Utility Screens

The PREV command reads the previous record from the currently accessed data set or temporary storage queue. This function is only available for temporary storage queues and for VSAM data sets that are defined to allow browsing. This command is the same as the READ PREV command in the File Utility.

Memory Display Screens

The PREV command displays data based on the previous address from the address table used in a Memory Display screen (2.2 and 9.2). Each time a new address is displayed on a Memory Display screen, Code Debug CICS records the address in a table.

The PREV command redisplays the address from the previous entry in the table. Every time the PREV command is used, the previous entry in the table becomes the current entry. You can use the PREV command in conjunction with the NEXT command to reposition to entries within this table.

The LEFT command performs the same function as the PREV command on the Memory Display screens (2.2 and 9.2).

 PRINT

The PRINT command is available on the Program Trace screen (2.4). This command allows you to spool a hard copy printout of the current program trace to your JES2/JES3 HOLD queue.

A second screen is displayed when you use the PRINT command. This screen prompts for additional routing information needed to produce the JES output. You must provide at least a JES SYSOUT class and DESTINATION for the output.

Printed output includes heading lines at the top of each page with the APPLID of the region, date and time the output was spooled to the JES HOLD queue, and userID of the owner of the Code Debug CICS debugging session from which the Program Trace screen was accessed. The heading lines also include the terminal ID associated with the Program Trace screen being displayed, the terminal ID associated with the actual trace output, and a summary of the operands specified on the PRINT command.

After the PRINT command spools the output to the JES HOLD queue, you receive a message indicating under what jobname the output was created and the destination to which it was routed. The jobname is the same as the CICS region in which you are running. You can then log on to TSO and use SDSF browse facilities to view the printed output. If you specify your userID as the destination, and then use SDSF’s OWNER userID command, your trace output will be listed among the print data sets available for viewing. After viewing the data using SDSF, which also provides you with the SDSF FIND command, you can choose to do any of the following:

• Use the PRINT command facility of SDSF to copy the output to another permanent data set.
• Use the O (output) line command of SDSF to release the output to a specific printer.
• Use the P (purge) line command of SDSF to purge the output, if you don’t want it.

If you are uncertain how to specify a print destination or how to use SDSF to view the printed output, contact your Code Debug CICS system administrator.

If no operands are specified for the PRINT command, the default is to print the entire program trace for the terminal currently being viewed. If source exists for a program in the trace, the actual source statements executed are printed. Lines indicating the range of offsets executed are printed for programs that have no source listing available.

The LABEL, PARA, and PROC operands are used to print a paragraph-level-only trace of program execution. A series of lines indicating the statement numbers executed in each paragraph or label are displayed. The source statements themselves are not displayed.

The TASK nnnnn operand lets you specify a task number (nnnnn) for which you want the trace displayed. This must be a task number for which trace currently exists in your program trace display.

Some examples of the PRINT command are:

The PSEUDOSOURCE command is used to create a temporary Assembler source image of a CSECT that does not have a matching BMC source listing. The source image created by this command is an Assembler view of the machine code in memory, regardless of the original language used to create that machine code. The PSEUDOSOURCE command can be abbreviated as PSEUDOSO, PSEUDO, or PS. Because multiple Assembler images can usually be generated to match machine code, the initial image may not exactly match the intent of the original source code. There could be areas of the program that were marked as instructions in the middle of what are really data areas. Before using another command, review the PSEUDOSOURCE output.

The CSECT name that specifies the machine code to be converted into Assembler source code can be specified in any of four ways:

• If no name is specified, the current load module and CSECT name are used.
• If the loadmod:CSECT is specified, the load module specified is loaded and the CSECT specified is used.
• If only the loadmod name is specified, the CSECT with the entry point of the current load module is used.
• If only the CSECT name is specified, the current load module is searched.

The hex-offset operand is used when you want to re-generate the source code beginning at the hex-offset specified. Code Debug CICS analyzes the underlying machine code beginning at this offset and reconstructs the pseudo-Assembler image starting at this offset. You would ordinarily use this operand when the initial pseudo-Assembler listing reflects incorrectly disassembled instructions or data. The hex-offset operand must be coded as a + (plus sign) immediately followed by one or more hexadecimal digits (0..F) specifying the hexadecimal offset within the CSECT.

If you want to regenerate the entire pseudo-Assembler listing, do not specify the hex-offset operand.

Usage Notes

1. 
   
   1. Once a source image has been created with the PSEUDOSOURCE command, that image can be redisplayed by entering the SOURCE command or the = 2.L command at any time in your debugging session.
   2. When multiple copies of the module exist, you must uniquely qualify the load module and CSECT name/program name combination. For example, PSEUDO LOADM1:CSECTA displays the source for CSECT CSECTA in load module LOADM1 and PSEUDO LOADM2:CSECTA displays the source for CSECT CSECTA in load module LOADM2.
   3. Code Coverage statistics are not collected for modules with generated pseudo-Assembler source.
   4. The PSEUDOSOURCE command does not create Assembler source if the specified CSECT has a matching BMC AMI Common Shared Services listing.
   5. Regenerating a pseudo-Assembler listing (once it has been generated) may cause breakpoints and/or keeps to be deleted. This can occur if the breakpoint or keep was placed on an incorrectly generated instruction which can happen when an area was examined and determined to be an instruction, but is really data.
   6. The DISCARD operand can be used to release the pseudo-Assembler listing created previously. Using it causes the storage associated with the generated pseudo-Assembler listing to be freed, and effectively restores the state of the program:csect to ‘No Source Available.’
   7. Code Debug CICS limits you to four pseudo-Assembler listings per debugging session. If you have previously created four pseudo-Assembler listings during your current debugging session and then use the PSEUDOSOURCE command on a fifth program:CSECT combination, the first pseudo-Assembler listing created will be discarded. A new pseudo-Assembler listing will be created for the program:CSECT specified.

PUT

The PUT command adds a message to an MQ queue. This command is available only in the File Utility.

READ

The READ command reads a record from a CICS data set, temporary storage (multiple record queues), or a transient data queue. This command is only available in the File Utility.

 For details about direction, see Variable-and-Common-Parameters.

UPDATE

Edit CICS Data set Record screen (5.1.3) only. If the system programmer established a READ UPDATE wait value in the global parameter FILE_UTILITY__READ_UPDATE_LOCKED, the user must issue a READ UPDATE command before updating a data set record using the REWRITE command. Code Debug CICS locks the record for this number of seconds when a READ UPDATE command is issued. This prevents other users from updating the record. The lock is released if any of the following conditions occur:

• 
  
  • A REWRITE command is issued to update the record.
  • Another command is issued for the data set.
  • The user exits from the Edit CICS Data set Record screen (5.1.3).
  • The number of seconds pass without issuing any command from the 5.1.3 screen.

If the wait time in the global parameter FILE_UTILITY_DATASET_READ_UPDATE_LOCKED is set to 0 (zero is the default), a READ UPDATE is not required before issuing a REWRITE command, and a lock is not placed upon the record.

REDISP (RED)

The REDISP command redisplays the current screen.

REFRESH (REF)

The REFRESH command redisplays the list of queues on the MQ Queue List screen (5.6.1).

RELEASE (REL)

The RELEASE command removes breakpoints, counts, skips, and (optionally) keeps, from the specified program.

program-name

Name of the program from which breakpoints are removed. The default value is the program name specified in the MODULE field.

ALL

Removes breakpoints and keeps from all programs based on the specified terminal ID.

terminal-ID

Terminal that owns the breakpoints. For XPED and XPRT users, the only valid entry is the current terminal ID. For XPSP users, both breakpoints and keeps are removed from any terminal specified.

ALL

Removes breakpoints from all other terminals. Valid only for XPSP users.

REMOVE (REM)

The REMOVE command decreases the length of the I/O area used in the File Utility. When a new record is read, Code Debug CICS automatically acquires a new I/O area and adjusts the length for the current length of the record. However, it is often helpful to change the length of the record, if allowed for the resource in use. To decrease the size of the I/O area, use the REMOVE command.

offset

Offset into the I/O area where the removal will occur. A valid entry is either a decimal value or a hexadecimal value from 0 to the current size of the I/O area minus 1. A leading plus sign (+) specifies a hexadecimal value. This parameter is relative to zero, that is, specifying 0 or +0 removes the data at the beginning of the I/O area.

If no I/O area exists (the record length is zero), REMOVE is invalid. When the removal occurs, Code Debug CICS deletes the number of bytes to be removed (second parameter) from the record beginning at the specified offset. All existing data in the record following the offset plus length is shifted to the left in the I/O area. Data within the specified limits is lost.

length

Specifies the length of data (number of bytes) to REMOVE from the I/O area. A valid entry is either a decimal value or a hexadecimal value from 1 (one) to the number of bytes remaining from the offset specified (parameter 1) to the end of the current I/O area. A leading plus sign (+) specifies a hexadecimal value.

Example 1:

Example 1 removes 20 bytes from the beginning of the current I/O area.

Example 2:

Example 2 removes 20 bytes of data starting at offset 64 (X’40’) into the I/O area. Bytes 0 through 63 remain unchanged. Bytes 64 to the end of the I/O area contain the data that was formerly in bytes 84 to the end of the I/O area. Thus, the data was shifted 20 bytes to the left.

REPEAT (REP)

The REPEAT command re-executes the most recently entered primary command or the value associated with the most recently pressed PF key.

REPL

The REPL command issues a DL/I REPL call to replace (update) an existing segment in a database. REPL is available only on the Edit DL/1 Segment screen (5.4.4). It can be used when the PSB in use was scheduled via a PCB call.

The REPL call must be preceded by a GHU, GHN, or GHNP call. You may then modify the segment in the I/O area and enter the REPL command to replace it in the database.

REPLACE

The REPLACE command replaces the generated SQL call to the Code Debug CICS SQL transfer data set. If the name does not exist in the data set, it is created. When the REPLACE command is used, the previously saved SQL call is overwritten and no longer available.

Once a call is saved in the SQL transfer data set, you can use the Code Debug CICS batch SQL utility DBSQLUTL to either print the call or copy it into another data set for inclusion in an application program.

key-name

A one- to eight-character name that is used to save the generated SQL call record in the data set.

RESAVE

The RESAVE command overlays the last excludes, which have been saved by the SAVE command, with the current level of excludes.

Use the EXCLUDE or FIND commands to establish a view of your program. You can then use the RESAVE command to resave those excludes, allowing you to recall them should your view of the source change. Use the RESTORE command to view the original excludes. Only one level of screen exclusions can be saved at a time.

RESET (RES)

The RESET command redisplays excluded lines and columns. The functionality of this command depends on the screen from which it is accessed:

• DB2 Build SQL Easy Query screen (5.5.2)
• Source Listing screen (2.L).

DB2 Build SQL Easy Query Screen (5.5.2)

The RESET command restores the display so that excluded columns are redisplayed on the DB2 Build SQL Easy Query screen.

Source Listing Screen

The RESET command redisplays excluded lines. It can also redisplay a range of excluded lines.

For details about range, see Variable-and-Common-Parameters.

COMMANDS, COMMAND, CMDS, CMD

Discards all pending BLOCK line commands such as CC, DD, etc. RESET COMMANDS discards only pending BLOCK commands for which no ending line command has been specified. Any line commands that can be processed (including block line commands) are processed normally and cannot be reset.

Redisplays all excluded lines. If a range is specified, redisplays only those lines within that range.

SPECIALS, SPECIAL, SPEC

Removes all special lines in the listing. The only special line currently supported on the Source Listing screen (2.L) is the <COLS> (column or ruler) line.

Deletes all symbolic labels specified for a particular listing. Symbolic labels begin with a period (.) and can be used to establish paperclip points within the listing. If a range is specified, only symbolic labels within the specified range are deleted.

Example:

This example redisplays lines in the range from the label .HERE through the .THERE label.

RESTORE

The RESTORE command restores a previous level of excludes on the source listing screens. If the EXCLUDE or FIND commands were used to establish a view of the program, the SAVE or RESAVE commands can save the excludes, allowing you to view the source changes. You can then recall the excludes using the RESTORE command. Only one level of screen excludes can be restored. Once the RESTORE command has been issued, a SAVE or RESAVE command causes the current set of excludes to be saved again.

RESUME (RSM)

The RESUME command resumes execution of a program that is currently at a breakpoint, abend, or storage violation trap.

The RESUME command is also used to end review mode, which is entered with the MONITOR command. From review mode, RESUME will reposition execution at the next instruction. You must then enter a GO command to release the task. There are no abbreviations or parameters in the syntax of the RESUME command while in review mode.

none

If no resume location is specified, execution continues from the current execution pointer.

statement

The statement number at which to resume execution, if source is available for the current program.

+offset

The offset at which to resume execution. The offset must be a valid hexadecimal number. The plus sign (+) is required.

ADDR address

The address at which to resume execution. The address must be a valid hexadecimal number.

The RETRIEVE command displays the last command entered in the COMMAND field. Because a stack of the last 20 commands entered in the COMMAND field is retained, repetitive use of the RETRIEVE command cycles through the stack. The RETRIEVE command does not redisplay the commands entered through any PF or PA keys. If Code Debug’s multiple command support was used, the RETRIEVE command will display the entire group of commands that were entered together.

REVERSE

Use the REVERSE command iteratively to change the current execution direction to review the sequence of instructions that led to the current breakpoint.

A requirement for using the REVERSE command is that you enter the MONITOR command at the point from where you want to review your program, or before you begin program execution. The MONITOR command activates review mode for program execution and makes it possible for you to review the path of forward execution.

After the MONITOR command is executed, the status of each statement as it is executed is kept in the review log. All changes occurring from the point where the MONITOR command was entered are logged.

Steps in Using REVERSE

1. Enter the MONITOR command to begin recording the instruction path and data.
2. Begin forward execution of your COBOL program.

3. When you reach a breakpoint or abend in your program, enter the REVERSE command. The command acts as a toggle that changes the review direction. During review mode, the Code Debug CICS status line will show the mode and direction.

   Important

   Entering REVERSE only changes the direction of review mode. It does not cause program execution to occur.

4. Enter GO n or GO to begin review of already executed commands. GO n moves the active arrow n lines in the current direction. GO 1 is recommended. The GO OVER command cannot be used while stepping in REVERSE mode.
   The GO command causes the active arrow to move until either the logical end of the review or a breakpoint is reached. The logical ends are:

   • 
     
     • where monitoring began or
     • the last instruction monitored.

   At the instruction where monitoring began, the review direction is automatically changed to forward. While in forward review mode, when the last instruction monitored is reached, review mode is automatically ended.

5. During review mode you may set and remove breakpoints and keeps, as well as use other Code Debug CICS screens. Data field values on all screens are READ-ONLY. Commands GOTO and MOVE are not valid during review mode.
6. To exit review mode, enter RESUME to return to the current execution location.

Usage Notes

• 
  
  • REVERSE displays the actual path that was taken during forward execution of the program.

• 
  
  • When executing in reverse, Code Debug CICS restores the values of all data items to their previous values. If you open a Keep window you can watch the values change interactively.
  • All Code Debug CICS commands are valid during review mode, except GOTO, SKIP, INSERT, and MOVE.
  • You cannot type over data displayed in Keep or Peek windows while in review mode.
  • While the MONITOR (review) mode is in effect, you can set and remove breakpoints and display data.
  • The GO and GO n commands perform the same as they do in normal execution, regardless of the direction. For example, you can repeatedly inspect the before and after values of a data item with respect to a COBOL MOVE statement in review mode by entering the sequence REVERSE, GO 1, REVERSE, GO 1, REVERSE, GO 1.
  • GO n executes n statements regardless of what module the statements are in.
  • The GO OVER command cannot be used while stepping in REVERSE mode.

REWRITE

The REWRITE command updates the currently accessed record to a data set and/or temporary storage. For temporary storage, this allows you to update a record without issuing a READ command. This command is only available in the File Utility.

For data sets, the system programmer can specify that updates occur without first reading the record for update, or that the READ UPDATE command be issued before a REWRITE command.

If the FILE_UTILITY_DATASET_READ_UPDATE_LOCKED parameter in the Code Debug CICS global parameter table is set to 0 (zero is the default), a REWRITE command can be issued for any record. A READ UPDATE is issued, immediately followed by a WRITE command to perform the update. This allows you to overlay changes made by someone else.

If the FILE_UTILITY_DATASET_READ_UPDATE_LOCKED parameter is greater than 0, you must issue a READ UPDATE command before issuing a REWRITE command. The record is locked for the number of seconds specified by the FILE_UTILITY_DATASET_READ_UPDATE_LOCKED parameter. You can then modify the record and issue the REWRITE command to update the record. For more information about READ UPDATE, see READ command.

 RFIND (RF)

The RFIND command finds the next occurrence of a string/area of previously found data. Code Debug CICS continues the search from the current location. If the data cannot be found, Code Debug CICS redisplays the current data and an error message.

The RFIND command positions to the next occurrence of previously found data based on the following conditions:

• If the previous FIND/EXCLUDE command used the FIRST or NEXT parameter, RFIND repeats the search forward through the data.
• If the previous FIND/EXCLUDE command used the LAST or PREV parameter, RFIND repeats the search backward through the data for the previously found data.
• If the data cannot be found, Code Debug CICS redisplays the current data and an error message.

RIGHT (RI)

The RIGHT command scrolls the current window to the right. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the current window depends on the cursor position when the RIGHT command is issued.

In the Memory Display screens (2.2 and 9.2), the RIGHT command and the PF key assigned to the RIGHT command function in the same way as the NEXT command. See NEXT (NXT). By the same token, the LEFT command functions in the same way as the PREV command. See section PREV (PRV).

The RIGHT command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display to the right so that the column in which the cursor is positioned becomes the leftmost column of data displayed. If the cursor is positioned outside of the data area, RIGHT CSR has the same effect as RIGHT PAGE.

HALF

Scrolls the display right half the width of the screen.

MAX

Scrolls the display right to show the last position of a line of data as the rightmost column of data. MAX is not valid when it is used with RIGHT or DRIGHT to scroll the Keep window.

nnnn

Scrolls the display nnnn columns to the right, where nnnn is a decimal value from 1 to 9999.

PAGE

Scrolls the display right the width of the screen.

RUNTO

The RUNTO command sets a onetime breakpoint on a statement. The onetime breakpoint pauses execution before the statement and is then automatically deleted. If the RUNTO command is issued from a trapped transaction, the onetime breakpoint is set, then the GO command is issued.

For details about location, see Variable-and-Common-Parameters.

ON

Sets the breakpoint.

OFF

Removes the breakpoint.

0

Set the breakpoint before the first statement in the program. 0 is the default.

CSR

The CSR option is only valid on the Source Listing screen (2.L).

If the cursor is located within the listing window of the 2.L screen when the command is entered, a onetime breakpoint will be generated as though the Z line command had been entered on that line. If the cursor is not located within the listing section, the RUNTO CSR command is not valid and will result in an error message.

+offset

Hexadecimal offset within a program. The plus sign (+) is required.

You may set multiple breakpoints on a statement.

• 
  
  • Multiple breakpoints (after, onetime, or count) can be set on one statement. However, if you set a skip on a statement that already contains after, count, or onetime breakpoints, SKIP deletes the set breakpoints.

Before breakpoints take precedence over onetime breakpoints. If a before already exists, the onetime cannot be set.

SAVE

The SAVE command saves one level of excludes on the Source Listing screen (2.L). If the EXCLUDE or FIND commands are used to establish a view of the program, you can use the SAVE command to save the excludes. This allows you to recall the information using the RESTORE command. Only one level of screen excludes can be saved. If a SAVE command has already been issued, this command has no effect. Use the RESTORE command to reissue the SAVE command at a later time. To overlay your currently saved excludes, use the RESAVE command.

 SELECT (SEL)

The SELECT command (default PF15) will cause the data currently pointed at by the cursor to be selected as an address to access other data. Not all data can be used as an address. The SELECT command may perform a function specific to a screen, or it may act as a “point and shoot” operator.

As a “point and shoot” operator, the SELECT command uses a predefined hotspot area to refer to a memory location. For hotspots, the underlying data is usually an 8-byte character field containing hexadecimal data. If one of the hotspot fields is selected, a Memory Display screen (2.2 or 9.2) will be displayed. If you started your session with the XPED or XPRT transaction, the 2.2 screen will be displayed. If you started your session with the XPSP transaction, the 9.2 screen will be displayed. When the screen has been displayed, you can use all of the functions normally available there. The END command (default PF3) will return you to the original screen from which you issued the SELECT command, instead of the Debugging Facilities menu or System Facilities menu.

The hexadecimal data defined as a hotspot is address mode sensitive. Consider an 8-byte hexadecimal key AABBAAAA to be broken into mode 31 (A) and mode 24 (B) characters. When the SELECT command is used and the cursor is located over a mode 31 (A) character, the key will be considered to be a 31-bit address. When the cursor is located over a mode 24 (B) character, the key will be considered to be a 24-bit address.

Several screen footings in Code Debug have hotspots defined, so footing hotspots are available on every screen. If the cursor is over a footing hotspot when the SELECT command is used, it will process that footing hotspot.

If a screen does not have any hotspots defined, using the SELECT command with the cursor in the data portion of the screen will do nothing, and Code Debug will react as though you had pressed Enter.

The syntax of the SELECT depends on the screen or hotspot from which it is accessed:

• Menus
• Memory Display screens (2.2 and 9.2)
• “Point and shoot” hotspots.

• List of CSECTs screen (2.6.1).

Menus

The SELECT command is used to select a topic from a menu. Type the SELECT command and move the cursor to the line defining the topic for selection. Press Enter or the associated PF key to select that topic or function.

Memory Display Screens

The SELECT command can also be used directly from the Memory Display screens (2.2 and 9.2) in one of two ways:

• 
  
  • Use the SELECT command and position the cursor on an address in the hexadecimal portion of the display. Press Enter to select that address.
  • Position the cursor to an address in the hexadecimal portion of the display and press the PF key (default PF15) that is assigned for the SELECT command.

When the cursor is positioned outside of the data portion of a Memory Display screen (2.2 or 9.2), the SELECT command causes Code Debug CICS to display the Select Address screen, which shows all entries in the address table.

Each time a new address is displayed on a Memory Display screen, Code Debug CICS records the address in a table. Use the SELECT command or the associated PF key to display this table. Directly access an address one of three ways:

• 
  
  • Type the letter S in the field preceding the desired address and press Enter.
  • Use the SELECT command and move the cursor to the desired address line. Press Enter to select that address.
  • Move the cursor to the line for the desired address. Press the PF key assigned to the SELECT command.

When the address is accessed, Code Debug CICS returns to the Memory Display screen. The selected address is used to display data starting at that address. The table only holds 16 entries, and the oldest entry is always the one that is lost. You may use the L (LOCK) line command to ensure that the address is not deleted from the table. If a locked entry is no longer needed, use the SELECT command to display the screen, then use the U (UNLOCK) line command to remove the lock, or enter UNLOCK on the Memory Display screen. For more information, see Line Commands for Code Debug for CICS. You can use the LOCK and UNLOCK primary commands on this screen.

If the cursor is in the data portion of a Memory Display screen (2.2 and 9.2) when the SELECT command is entered, Code Debug CICS uses the full word address at the cursor location to display the next screen. This procedure is the same as using the
USE CONTENTS field on the Memory Display screens.

List of CSECTs Screen (2.6.1)

The SELECT command can be used on the List of CSECTs screen (2.6.1) to select a CSECT. Simply enter the SELECT command with the desired CSECT name as a parameter. Code Debug will select the CSECT and position it to the top of the display.

List of DLL Functions Screen (2.6.F)

The SELECT command can be used on the List of DLL Functions screen (2.6.F) to select the CSECT containing the function that you want to debug. Simply enter the SELECT command with the desired DLL function name as a parameter. Code Debug selects the CSECT containing that function and positions the function at the top of the display.

Various hotspots have been defined for “point and shoot” operation of the SELECT command. They are indicated with underlined text in the following figures. Note that the text is not underlined on the actual screens.

FOOT Register

When the footing area is set to display registers, the defined hotspots displayed in the following figure will be active.

The defined hotspots displayed in Source Listing Screen (2.L) Hotspots, all in the keep window, are active for the Source Listing screen (2.L).

The hotspots are only valid if they are displayed in hex as indicated by the highlighted literal 'X preceding the field. They are only valid if the data is scrolled completely to the left, i.e. the scroll indicator in position one is a dash (-). Additionally, the hotspot can only be valid if the field is not a Halfword or EQUated value. In Source Listing Screen (2.L) Hotspots, there would only be four hotspots available. The REPEATS(13) value of 1 is not considered a hotspot because there is no 'X preceding it.

SET

The SET command allows you to change selected debugging session parameters and changes the settings on the 0.1 screens. If the profile data set is installed at your site, the parameter settings are saved in your user profile when you exit the session. For more information on session profiles, see Establishing-a-Profile.

ALARM

Turns ON or OFF the audible alarm that sounds when an error is detected.

ON: Allows the alarm to sound when an error is detected. An error message is always displayed. If neither the ON nor OFF parameter is used, ON is the default.

OFF: Prevents the sounding of the alarm when an error is detected; however, an error message is always displayed.

ALT

Turns ON or OFF the alternate screen size capability for 3270-type Model 3, 4, and 5 terminals. This command has no effect if the terminal does not support alternate screen sizes or the terminal control table (TCT) has not been generated with alternate screen size support.

When an abend is trapped and ALT ON is entered, Code Debug CICS switches to the alternate screen size, even if the trapped transaction was not using the alternate screen size. If the task is resumed, the default screen size for the transaction is restored.

OFF: Turns OFF the alternate screen size capability and resets to the default screen size.

AUTOKEEP

Turns ON or OFF the display of variable data for all variables participating in the current statement while stepping. The default is ON.

OFF: Only explicitly kept variables (set via the KEEP primary or K line command) will be displayed during stepping.

BTRACE

Controls the updating of an internal branch trace table used for diagnostic purposes. The default is YES.

NO: Unless Code Debug CICS Customer Solutions has requested that you run with this option set to YES or FULL, it may be set to NO to save CPU.

CMDSIZE

Allows users to set the command line size to 1 (the default), 2, or 3 lines.

DELIM

Specifies the delimiting character to be used to separate multiple Code Debug CICS primary commands entered together. Any character is a valid delimiter except alphanumeric characters (a to z, A to Z, and 0 to 9), period (.), comma (,), blank ( ), underscore (_), and equal (=). The default is a semi-colon (;).

DATETIME

Turns ON or OFF the requirement that the date and time stamps match for the program being tested and its corresponding source listing file. The default is ON.

OFF: Code Debug will allow date and time stamp mismatches between programs and their source listing files. A warning message will be displayed along with the program source.

DELAY

Specifies a default delay interval for the GO command. This value is the number of seconds you wish to wait between the execution of successive statements. The range for this value is between 0 (zero) and 20 seconds. The default value for this parameter is 0; however, this value can be overridden by the system programmer or the value set in your user profile.

FOOT

The foot parameter turns ON and OFF footing information at the bottom of the screen. It also allows you to establish the type of data that you would like displayed in the footing area. Footing information is never displayed at the bottom of a menu. The following types of footing information can be displayed at the bottom of your screen:

• 
  
  • ANALYZE
  • DATA
  • FLOAT
  • KEYS
  • MENU
  • OFF
  • ON
  • REGS
  • STATUS
  • SOURCE

Following is a brief description of each of these FOOT parameters.

ANALYZE: This footing display contains the following statement analysis information which is initiated through the COUNT command:

• 
  
  • STATEMENTS TO BE COUNTED
  • COUNTED STATEMENTS EXECUTED
  • COUNTED STATEMENTS NOT EXECUTED
  • PERCENTAGE STATEMENTS EXECUTED
  • TOTAL COUNT
  • HIGHEST COUNT
  • HIGHEST COUNT STATEMENT
  • PARA.

DATA: This display contains four lines of block hex showing the contents of the area pointed to by the result of the CALC command. For information on the CALC command, see CALC (??).

KEYS: This display contains the PF key settings currently established for your debugging session. PF key settings can be modified using the KEYS command or the Primary PF Key Settings screen (0.2) or with the SET PFnn command.

MENU: This display contains a menu of the screens that are available in the functional area you are currently using. You can transfer to any of the screens in this area by typing the screen number of your choice.

OFF: Turns OFF the footing information at the bottom of the screen.

ON: Turns ON the footing information at the bottom of the screen with MENU content.

REGS: This display contains the current program register contents, PSW of where the break/abend has occurred, and the current assembler instruction. The contents of the registers are modifiable. The data is only displayed if you are in a break/abend state. If you are not in a break/abend state, a warning message is displayed to indicate this.

FLOAT: If the machine that CICS is running on does not support IEEE floating point, then the display contains the current program’s:

• 
  
  • general register contents (R0 through R15)
  • standard floating point registers (F0, F2, F4, and F6)
  • the PSW of where the break/abend has occurred
  • the offset within the current CSECT
  • the current Assembler instruction.

If the machine does support IEEE floating point, then only the 16 IEEE floating point registers are displayed in this footing.

This data is displayed only if your program is in a break/abend state. Otherwise, a warning message is displayed.

You can modify the contents of general and floating point registers by overtyping the data. Overtyping rules are as follows:

• 
  
  • Partial overtyping is not flushed out automatically.
  • Entering one or more spaces or pressing Erase EOF flushes unwanted digits. The data is padded with binary zeros and right justified.
  • Entering Rn followed by one or more spaces or pressing Erase EOF in a general register field copies general register n to the overtyped general register. Rn can be entered on any digit position.
  • Entering # n followed by one or more spaces or pressing Erase EOF in a floating point register field copies floating point register n to the overtyped floating point register. # n can be entered on any hex digit position.
  • Pressing Erase EOF at the first digit position restores the general or floating point register to its value at the last breakpoint or GO.
  • Modified registers will be committed on a GO 1 or GO.

STATUS: This display contains a summary of the current abend and terminal information.

One or more abbreviations indicating which product functions or options were active at the time of the break or abend may be displayed in the STATUS field.

IKEEP

Turns ON or OFF the availability of the Intelligent Autokeeps feature during stepping. For more information, see Intelligent Autokeeps.

OFF: Causes the keep window to bypass the display of intellikeeps and the removal of duplicate autokeeps.

JUSTIFICATION (JUSTIFY, JUST)

Clips the current source listing so that extraneous data to the left and the right of the source lines is removed from the display. In addition, all lines prior to the first source line and following the last source line are also removed from the display. This provides a more source-like display, but prohibits the viewing of areas such as the cross reference. ON is the default.

ON: Clips the display.

OFF: Restores the display of all data provided in the source listing.

LOADTRAP

Loads saved traps at session start.

ON: (Default) Loads saved traps at session start.

OFF: Does not load saved traps at session start.

KEEPS

Opens or closes the keep window on the Source Listing screen (2.L). This allows you to perform the majority of debugging functions from the Source Listing screen (2.L). This window can also be closed via this command.

SET KEEPS n or SET KEEPS ON n or SET KEEPS ON: Enables the keep window on the Source Listing screen (2.L). This window is displayed when the program is in a break/abend state. You may size this window to 0 or any number 3 to 11. The default is 5. This makes the window n lines deep. Note that if you resize your keep window, any line commands entered since the Enter key or PF key was last pressed are ignored. The SET KEEPS n command accepts a numeric value of 0 (zero) and treats it as though the keyword OFF was entered.

SET KEEPS OFF: Closes the keep window on the Source Listing screen (2.L). Note that any line commands entered since the Enter key or PF key was last pressed are ignored. The SET KEEPS n command accepts a numeric value of 0 (zero) and treats it as though the keyword OFF was entered.

Specifies a default maximum number of statements to execute when the delay value of the GO command is greater than zero (0). The maxstep-value must be in the 1 to 99 range.

OPTIMIZE

Turns ON or OFF the internal screen optimizer.

ON: Turns ON screen optimization, which provides smoother displays, because only modified data is sent to the screen. The default is ON.

OFF: Disables screen optimization. When screen optimization is disabled, a SEND/ERASE is issued every time a screen is displayed. This may cause the screen to flash.

Specifies whether program optimized warnings are to be displayed in the footer section of the screen.

ON: Displays optimized warnings on the first line of the footer. The default is ON.

OFF: Disables optimized warnings in the footer section.

PFnn

Specifies the Code Debug command to be executed when a particular PF key is pressed.

nn: PF key number. Valid entries are 1 to 24.

command: Command to execute when you press the PF key.

description: Label to display for this PF key in the footing area of the screen. The footing is displayed with the SET FOOT KEYS command. The maximum label length is eight characters. These labels are also used for the PF key buttons displayed when running Code Debug CICS using the 3270 Web Bridge. For more information, see 3270-Web-Bridge-Support. If the description is blank, it is the same as the command.

PL/I based variable (pointer-var -> based var)

Specifies a pointer for a PL/I based variable for use when displaying a data variable on the Break/Abend screen (2.1), Variable Storage screen (2.3), or Source Listing screen (2.L). The address of pointer-var will remain the base for based-var. In order to change the base address, you must reissue the SET command.

pointer-var: A variable whose address will be used as the pointer of based-var.

->: Must be entered without leading or trailing blanks.

based-var: A based variable which has not been declared either with an implicit pointer of type pointer or via a function call such as ADDR(...). An attempt to use this syntax with a based variable that has an implicit pointer will be flagged with an error.

PROTECT (PROT)

Turns storage protection ON or OFF. Storage protection allows you to check your program or transaction for possible storage violations.

The request is effective immediately within the current CICS task for this LINK/enclave level and any enclave levels created from this point on. Programs within the current CICS task at a higher (existing) LINK/enclave level are not included in this request.

OFF: Disables storage protection.

SAVETRAP

Saves traps automatically at session end.

ON: (Default) Saves traps automatically at session end.

OFF: Does not save traps automatically at session end.

REGS

Specifies the display format for the General Purpose (GP) registers. These registers are shown on the “Assembler Break/Abend” screen (2.20) and on the REGISTERS footing.

Valid values are:

64: (Default) Display all positions of the GP registers.

32: Display only the lower 32 bits of the GP registers.

SOURCE (SRCE, SRC)

Displays the Source Listing screen (2.L) or the Break/Abend screen (2.1) whenever a break or abend is encountered.

ON: Displays the Source Listing screen when a break or abend is encountered.

OFF: Displays the Break/Abend screen when a break or abend is encountered.

SUPPORT

Used only when directed by Code Debug CICS Customer Solutions. When ON is specified, a portion of the Code Debug CICS screen heading line is overlaid with the current date and time.

ON: Turns ON the SUPPORT feature.

OFF: Turns OFF the SUPPORT feature. OFF is the default.

 TRACE

Turns ON or OFF the program TRACE feature. When a transaction is executed and a source listing for the program exists, the statement level execution can be viewed on the Program Trace screen (2.4).

The request is effective immediately within the current CICS task for this LINK/enclave level and any enclave levels created from this point on. Programs within the current CICS task at a higher (existing) LINK/enclave level are not included in this request. Deletion of a Trace rule by primary command SET TRACE OFF causes all trace data collected as a result of that rule to also be deleted. Review your trace results on screen (2.4) before deleting the rule.

ON: Turns ON the TRACE feature.

OFF: Turns OFF the TRACE feature. OFF is the default.

TRANSLATE

Allows you to override how non-alphanumeric characters are displayed in output fields.

SET TRANSLATE ON causes all existing profile-level translate overrides to be put into effect. SET TRANSLATE OFF causes all profile-level translate overrides to be disabled while retaining the previously-requested values. SET TRANSLATE RESET causes all profile-level translate overrides to reset to their original default substitution values.

The hexadecimal value yy replaces hex value xx in screen output fields. Specifying ND causes a period character (x'4B') to be substituted for hex value xx. SET TRANSLATE xx RESET causes all previously entered TRANSLATE commands for hex value xx to be undone, allowing the original default substitution to occur. Omitting the second parameter causes hex value xx to be replaced with hex value xx.

Validation is done on the replacement value to ensure it is not a 3270 order or SO/SI controls. 3270 orders and SO/SI controls include: x'05', x'08', x'0E', x'0F', x'11', x'13', x'1D', x'28', x'2C', and x'3C'. For further information about 3270 orders, see IBM 3270 Information Display System Data Stream Programmer's Reference (GA23-0059-xx).

Any SET TRANSLATE operand other than OFF also has the effect of turning this option ON.

The current settings for the TRANSLATE option and the entire output field translate table are displayed and may be altered on the SET PROFILE DEFAULTS (0.1) screen.

TRAP

Turns ON or OFF the ABEND TRAP feature. This feature allows you to trap any abend that occurs at your terminal or, optionally, to your user ID during a debugging session.

ON: Turns ON the TRAP feature. ON is the default.

OFF: Turns OFF the TRAP feature.

WIDEHEX

Turns ON or OFF the alternate format for displaying vertical hex in keep windows and on the Working Storage screen (2.3). The standard format for vertical hex shows up to 24 positions of each field on a screen using three screen lines per field to display field name, field attributes, and the data vertically (character, zone, and decimal). When WIDEHEX is ON, up to 74 positions of each field will be displayed, using five screen lines per field as follows:

• 
  
  • the field name and attributes are displayed on line 1
  • data is displayed vertically (character, zone and decimal) on lines 2, 3, and 4
  • a scale is displayed on line 5.

Because five screen lines are used, SET WIDEHEX ON impacts the KEEPS value. (See KEEPS.) When WIDEHEX is OFF, the value for KEEPS can be from 3 to 11. When WIDEHEX is ON, the value for KEEPS can only be from 5 to 11. Attempting to SET WIDEHEX ON while the value for KEEPS is 3 or 4 will generate an error message and WIDEHEX will remain OFF.

 SHOW (SH)

The SHOW command modifies the format of selected screens to display data in different forms. The command’s function depends on the screen that is accessed:

• Source Listing screen (2.L)
• Edit DL/1 Segment screen (5.4.4)
• Db2 Screens in the File Utility
• File Mapping
• Variable Storage screen (2.3) and Keep Display Areas
• Program Trace screen (2.4)
• SHOW WHEN command.

Each is described separately.

Source Listing Screen

The following SHOW command syntax acts upon the source listing area of the Source Listing screen (2.L). Use the RESET command to reset the screen display.

ALL

Shows all program labels, COBOL paragraphs, and PL/I procedures in the program, as well as any statement where one of the following commands is defined:

• 
  
  • 
    
    • AFTER
    • BEFORE
    • COUNT
    • KEEP
    • LABEL
    • ONETIME
    • PARA
    • PROC
    • SKIP
    • SYMBOLIC

Edit DL/1 Segment Screen

The following SHOW command syntax allows you to change the display format on the Edit DL/1 Segment screen (5.4.4).

DATA

Displays data in the defined I/O area. This portion of the display allows for four modes of data display. Use the HEX and USING commands to display data in the following formats:

HEX OFF: Displays the data in character mode.

HEX or HEX ON: Displays the data in vertical hex mode.

HEX DUMP: Displays the data in dump mode.

HEX OFF and USING: Formats the data in a COBOL or PL/I 01 level.

KEYS

Rebuilds the SSA list to reflect the current position within the DL/I database, based upon the last DL/I call made. It builds qualified SSAs and then displays the newly built list. This SSA list is then used in subsequent DL/I calls.

SSA

Displays the current list of SSAs being utilized.

Db2 Screens in the File Utility

The following SHOW command syntax allows you to display the SQL call generated by an EASY QUERY. It also allows you to execute the result table from the EASY QUERY.

RESULT

Displays result table.

SQL

Displays generated SQL.

File Mapping

The following SHOW command syntax displays information in the SHOW field, which is located between the field name and data. For more information on File Mapping screens, see USING.

FORMAT (F)

Displays, in bytes, both the length and format of the field.

LINE (L)

Displays the line number on which the field was defined.

OCCURS

Displays the current occurrence for subscripted or indexed fields.

OFFSET (O)

Displays the cell type, number, and offset from the cell.

PICTURE (P)

Displays the picture clause for the COBOL data names.

Program Storage Screens (2.3) and Keep Display Areas

The following SHOW command syntax acts upon the variables and values that are displayed in the keep areas of the Source Listing screen (2.L), the Break/Abend screen (2.1), and the Program Storage screens (2.3).

Languages Operands Support

The following table shows the languages that each operand supports.

Supported Operands by Language

ADDRESS

Displays the address of the data item (C Only). If the data item is a pointer, the address of the pointer is displayed, not the address that it contains.

ATTRIBUTE

Changes the display of data items so that only the data name and a 40-position extended information area are displayed. This format displays the current attributes associated with the data item. The information area can be scrolled left or right. Scrolling right displays the same information as the SHOW OFFSET command. Scrolling right again shows the same information as the SHOW QUALIFIED command.

CBL88

Displays the contents of all COBOL 88 level variables. The associated parent data item is also displayed. The default is ON. To remove all 88 level fields from the display, enter SHOW CBL88 OFF.

CELL

Displays the type and cell number of COBOL locators.

DATA

Changes the display of data items so that only the data name, a short attribute area, and a 24-position data value area are displayed. The LEFT and RIGHT commands can be used to scroll the data value area. A scale line is displayed.

DATAONLY

Changes the display of data items so that the data name and a 40-position data value area are displayed. The LEFT and RIGHT commands can be used to scroll the data value area. A scale line is displayed.

DSECT

Displays the DSECT/CSECT name in which the data label is defined. This parameter is only valid for Assembler programs.

FORMAT

Displays the format (Assembler notation) in which the data is stored for a COBOL data item.

LENGTH

Displays the number of bytes of storage occupied by a data item. This is a decimal value.

LINE

Displays the line or statement number where this data item is defined.

OFFSET

Displays the offset within working storage or PL/I DSA where this data item is found. This value is hexadecimal for Assembler and COBOL and decimal for PL/I.

QUALIFIED

Changes the display of data items so that the data name and a 40-position extended information area are displayed. This format displays the fully qualified name for the data item. The extended information area can be scrolled left and right. Scrolling left displays the same information as the SHOW OFFSET command. Scrolling left again displays the same information as the SHOW ATTRIBUTES command.

USING

Displays the current active USING or base register for the data label. If no addressability is established, ??? will be displayed. If addressability has been established, the general purpose register will be displayed. This parameter is only valid for Assembler programs.

Program Trace

The following SHOW command syntax allows you to change the display to a list of paragraphs, procedures, or labels that have been executed, thus omitting the actual statements themselves. This enables you to examine the flow of a program in a compact form.

ALL

Displays a complete statement trace.

LABEL

Displays a label trace.

PARA

Displays a paragraph trace.

PROC

Displays a procedure trace.

Show When Screen (C, COBOL and PL/I only)

The SHOW WHEN command is equivalent to typing =2.7 and transfers you to the Show When screen (2.7). This screen lists active when-conditions that have been established during your debugging session.

 SKIP (SKI, S)

The SKIP command temporarily skips execution of a statement during the debugging process. Either conditional or unconditional skips can be set. The SKIP command provides several options for setting and deleting skips within a program.

For details about location and if-condition, see Variable and Common Parameters.

ON: Sets a skip.

OFF: Removes a skip.

+offset

Hexadecimal offset within a program. The plus sign (+) is required. Only valid for Assembler programs.

You may set either conditional or unconditional skips on a statement.

• 
  
  • Conditional skips are set with an IF clause that provides Code Debug CICS with a selection criterion. Conditional skips cause a statement to be skipped only if the condition is met. You can only set one conditional skip on a statement.
  • Unconditional skips always cause a statement to be skipped when they are encountered. No IF clause is used.

Multiple breakpoints (after, before, count, or onetime) can be set on one statement. However, if you set a skip on a statement that already contains after, before, or onetime breakpoints, SKIP deletes the set breakpoints.

Usage Notes

The if-condition is executed according to the following conditions:

• 
  
  • The tests between the first operand and the second operand are made as logical comparisons, that is, CLC instructions.
  • Code Debug CICS makes comparisons using the length of the first operand or the second operand, whichever is shorter.
  • If the second operand is a numeric value, the data is converted to a format compatible with the first operand unless the second operand is in apostrophes or quotes. Comparisons are made using the length of the first operand.
  • Before the statement executes, Code Debug CICS evaluates the first operand and compares its value with the second operand value using the specified operator.
    • If the condition is met, the statement is skipped.
    • If the condition is not met, normal program execution continues.

Examples:

SKIP 300 IF COUNT EQ 50 Sets a skip at statement 300 that is taken only upon the fiftieth execution of statement 300.

SKIP ON +1FEA IF R9 EQ X'000000FB' Sets a skip at offset 1FEA that is taken only if the value of register 9 is equal to X’000000FB’.

SKIP ON ALL PARA IF WA-RATE NE 10 Sets skips at all paragraphs in a COBOL program that are taken if the numeric value of the WA-RATE variable is not equal to 10.

SKIP ALL WA-HOURS IF WA-HOURS EQ '002050' Sets skips at all statements in a COBOL program that refer to the WA-HOURS variable. Skips are only taken if the value of WA-HOURS is equal to the string 002050.

SKIP ALL WA-HOURS IF WA-HOURS EQ 2050 Code Debug will convert 2050 to a format compatible with WA-HOURS. Then skips will be taken only if the numeric value of WA-HOURS is 2050.

SKIP ALL WA-HOURS IF WA-HOURS LT ZERO Sets skips at all statements in a COBOL program that refer to the WA-HOURS variable. Skips are only taken if the numeric value of WA-HOURS becomes less than 0.

SKIP ALL WA-HOURS IF WA-HOURS NOT NUMERIC Sets skips at all statements in a COBOL program that refer to the WA-HOURS variable. Skips are only taken if the value of WA-HOURS becomes non-numeric.

If an attempt is made to use the SKIP command to skip the last executable statement of a program, a COBOL EXIT statement, or a PL/I END statement, Code Debug CICS will prevent the skip from being set and alert the user by highlighting the skip and issuing an illegal skip message.

SOURCE (SOU)

The SOURCE command ends the current function and transfers to the Source Listing screen (2.L). From this screen you can view your current program and debug it.

SVCDUMP

Entering the SVCDUMP command produces an MVS SVC dump of the address space. The SVCDUMP command is only available to XPSP users.

TERM

The TERM command terminates a currently scheduled DL/I PSB. The TERM command is performed only if a PSB has been previously scheduled on the Edit DL/1 Segment screen (5.4.4) using the PCB command.

If a PSB is currently scheduled, Code Debug CICS displays the message PSB IS SCHEDULED to the right of the RECFM field on the screen. If a PSB is not scheduled, the message PSB IS NOT SCHEDULED is displayed.

The TERM command terminates the currently scheduled PSB. Any ISRT, REPL, and DLET calls made while the PSB was scheduled are retained. To roll back changes made, use the CANCEL command instead of the TERM command.

The Code Debug CICS global parameter FILE_UTILITY_DLI_PSB_SCHEDULE_MAX specifies a PSB time-out limit. This prevents a PSB from unintentionally locking out access to a DL/I database when the terminal is left active through the Edit DL/1 Segment screen (5.4.4). If processing on a database takes place (that is, a DL/I call is performed while a PSB is scheduled), the time-out counter is reset to a full 2 minutes (the default). If no DL/I calls are performed on the PSB within the time-out limit, Code Debug CICS automatically terminates the PSB, rolls back any changes in progress, and displays a message. If the PSB is not terminated before leaving the Edit DL/1 Segment screen (5.4.4), Code Debug CICS automatically cancels any changes in progress.

TOP

The TOP command scrolls to the start of the data currently displayed on the screen. The first line of data available is displayed as the first line in the data area. This command is the same as the UP MAX command. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the current window depends on the cursor position when the TOP command is issued.

UNLOCK

The UNLOCK command is used on the Memory Display screens (2.2 and 9.2) or the Select Address screen to unlock the current address in the select address table. The table holds up to sixteen entries. When the table is full, the oldest entry is automatically deleted to allow for the next entry. Locking an entry prevents it from being deleted when a new entry is added. Unlocking an entry allows it to be deleted. See SELECT (SEL).

label

Used as search criteria for unlocking an entry. If the label is found, the entry is unlocked. If the label is not found, an error message is issued, and the UNLOCK command is redisplayed. If the label parameter is not used, the current entry is unlocked.

UP

The UP command scrolls backward through the data currently displayed on the screen. On the 2.L screen, where multiple windows can exist (one each for Keep displays and Source displays), the current window depends on the cursor position when the UP command is issued.

The UP command is used with a scrolling value. The default scrolling value is taken from the SCROLL field on the screen unless it is overridden by entering a temporary scroll value on the COMMAND field. The valid scrolling values are:

CSR

Scrolls the display up so that the line on which the cursor is positioned the bottom line of data. If the cursor is positioned outside of the data area, UP CSR has the same effect as UP PAGE.

HALF

Scrolls the display up n/2 lines, where n is the number of lines of data that can be displayed on a screen.

MAX

Displays the first line of data available as the top data line.

nnnn

Scrolls the display up nnnn lines, where nnnn is a decimal value from 1 to 9999.

PAGE

Scrolls the display up n lines, where n is the number of lines of data that can be displayed on a screen.

UPDATE

The UPDATE command transfers from the Browse MQ Queue Message screen (5.6.2) to the Update MQ Queue Message screen (5.6.3) with the currently accessed message.

 USING

The USING command formats the current I/O area according to the specified COBOL or PL/I 01 level data name. The data name must be defined in the program specified in the MODULE field on the screen. The program must have been processed by the BMC language processor. The USING command is available in the File Utility screens (5.1.3, 5.2.3, 5.3.2, 5.4.4, 5.5.6, 5.6.2, and 5.6.3) to map the current I/O area.

To modify the display after the USING command is used:

• Use the HEX command to switch display modes out of the USING formatted mode, or use the USING OFF form of this command. To return to USING formatted mode, type the USING command without a parameter.
• Navigate through the record using the LOCATE and FIND commands.

If the record contains any OCCURS DEPENDING ON clauses, the specified name must be within the record. You must check for the correct contents of these fields. The record will not map correctly if the field specified in an OCCURS DEPENDING ON clause does not contain the correct value.

dataname

COBOL and PL/I 01 level data name in the current program. Data names discarded by using the COBOL compiler’s storage optimization function are not supported.

VERIFY

The VERIFY command for Assembler programs displays underlying object code in memory that corresponds to the Assembler source statement on the Source Listing screen (2.L).

You can modify the Assembler instructions by overtyping the VERIFY fields.

The VERIFY command is not supported for programs residing in (E)RDSA.

Statement

Sets a verify at the specified statement number.

Label-name

Sets a verify at the specified label in the program listing.

ALL, ALL STATEMENT, ALL STATE

Sets a verify at all supported statements in the program listing.

VS transfers to the Variable Storage screen (2.3) for PL/I.

 WHEN (W)

The WHEN command establishes conditions to be monitored during the execution of a C, COBOL, or PL/I program. You can set several when-conditions in one program with a single WHEN command.

For details about the when-condition parameter, see Variable-and-Common-Parameters.

Usage Notes

Within each conditional statement, the comparison is done according to the following rules:

• 
  
  • The tests between the first operand and the second operand are made as logical comparisons.
  • Code Debug CICS makes comparisons using the length of the first operand or the second operand, whichever is shorter.
  • If the second operand is a numeric value, the data is converted to a format compatible with the first operand unless the second operand is in apostrophes or quotes. Comparisons are made using the length of the first operand.
  • Use the AND, OR, and parentheses when compound conditions are necessary.

Examples:

WHEN WA-HOURS = '000500' Once the when-condition is met, and you use the GO command, execution resumes. While the condition remains true, Code Debug will ignore it. If the condition becomes no longer true, Code Debug will resume testing for it and will treat the condition as another breakpoint if it is met again.

WHEN WA-HOURS=500 Code Debug will convert 500 to a format compatible with WA-HOURS.

WHEN WA-HOURS LT ZERO Program execution halts only if the numeric value of WA-HOURS becomes less than 0.

WHEN WA-HOURS NOT NUMERIC Program execution halts only if the value of WA-HOURS becomes non-numeric.

WRAUX

The WRAUX command writes data to auxiliary temporary storage. This is for use only with temporary storage queues. This command is available only in the File Utility.

WRITE

The WRITE command adds a record to a data set, temporary storage, and transient data destinations (output only). This command is available only in the File Utility.

For the WRITE command to execute on keyed data sets, change both the KEY field on the screen and the data in the record.

WS

The WS command ends the current function and transfers to one of the Data Area screens (2.3). This transfer can occur only if you are currently in a break/abend state. The program name automatically changes to the program in which the break or abend occurred.

= Command

The = command is used to transfer you from one Code Debug CICS function to another.

The variable screen-id is the identification number of a  Code Debug CICS screen.

Because Code Debug CICS is based on a menu structure similar to ISPF/PDF, you can transfer from one screen to another in several ways:

• Transfer from one function to the highest level menu in Code Debug CICS. To transfer from the Storage Protection screen (1.8) to the Session Control Menu (1), type =1 from the 1.8 screen, then press Enter.
• Transfer out of the Code Debug CICS session. To transfer to the Exit Session screen (X), type =X and press Enter.