CNTL Commands and Menus

1
caitsd-11-0
1
The primary task of CA InterTest for CICS is to monitor programs so that it detects and prevents errors. The CA InterTest for CICS CNTL transaction performs all monitoring functions.
The CNTL Monitoring Command Builder menu topics are included here as a reference for CA InterTest for CICS users familiar with this method of performing monitoring functions from previous releases.
CNTL Capabilities
Use the CNTL transaction to perform these functions:
  • Monitoring
  • Breakpoints
Monitoring
Set and remove monitoring for one or more programs, all the programs executed by a transaction, or all the programs executed from a terminal.
Breakpoints
Set and remove unconditional or conditional breakpoints.
Set and remove request breakpoints prior to CICS commands, calls to DL/I or DB/2, and calls to database software.
Monitoring Options
With the CA InterTest for CICS CNTL feature, you can:
  • Set and remove statement tracing options for COBOL programs, including data monitoring
  • Dynamically replace one or more CICS resources (programs, files, temporary storage, transient data queues) used by a program
  • Override default protection rules
  • Set and remove special monitoring options, such as limiting the number of times a program is monitored or preventing a program from updating a file
  • Provide symbolic support for programs that consist of separately compiled modules brought together when the program is link-edited (composite support)
  • Set and remove non-interactive monitoring sessions for a program executed by a transaction, or for all programs executed from a terminal
Status Display, Utility, and System Options
With the CA InterTest for CICS CNTL feature, you can:
  • Display the status of monitored programs, transactions, or terminals
  • Display the contents of CA InterTest for CICS tables and files
  • Reset monitoring for a recompiled program
  • Establish monitoring options for the entire system
Resume Task Execution
With the CA InterTest for CICS CNTL feature, you can resume execution of a task halted at a breakpoint.
Use the CNTL menus and screens or CNTL commands to perform all of the functions listed in the previous two sections. Additional options, specified by commands, are available to perform more specialized functions.
Initiate Monitoring
CA InterTest for CICS provides many ways of initiating monitoring and performing other CNTL functions:
  • Source listing facility
  • ITST menus and fill-in screens
  • CNTL menus and fill-in screens
  • CNTL commands
With the CNTL facility use one method exclusively or use the mix-and-match method -- even during one test session, depending on your specific testing needs.
Example
Use the source listing facility to initiate monitoring and set breakpoints, the CNTL menus and screens to set special options, and a single-line command to resume execution of a task.
The easiest way to turn on monitoring and set breakpoints for a single program is to use the source listing facility. For a new or infrequent user, this method is strongly recommended. Turn on monitoring by pressing a PF key, and set a breakpoint by entering a single keystroke directly on your program's source listing. For more information about this facility and what to do when your program halts at a breakpoint, see Source Listing Facility for InterTest.
To take advantage of the full range of CA InterTest for CICS monitoring capabilities, use the CNTL Monitoring Command Builder menus and screens or enter CNTL commands. Nearly all the monitoring functions are implemented either way, so select the method that suits you best.
The CNTL Monitoring Command Builder menus and screens make it easy for you to specify the necessary information without worrying about command syntax. All you have to do is select the function you want and enter the data -- CA InterTest for CICS creates the right command for you. Online Help is available from every screen using PF1 to provide you with more information.
If you prefer, enter single-line CNTL commands to specify monitoring functions. More experienced users often find it faster to enter commands directly.
To access online Help when entering single-line commands, type Help on a clear screen. CA InterTest for CICS displays the Transaction Codes screen. Press
Enter
and CA InterTest for CICS displays the help facility master menu. Two main topics (program monitoring and breakpoints) and their associated subtopics provide information on CNTL commands.
Monitor Command Building Menus and Screens
This section describes how to use the CNTL Monitoring Command Builder menus and screens to perform the following CNTL functions. The order in which CNTL functions are described corresponds to their order on the Function Selection Menu.
  • Function Selection Menu
    The main menu for selecting CNTL functions.
  • Setting and Removing Monitoring
    Begin and end monitoring for programs, transactions, or terminals.
  • Setting and Removing Unconditional Breakpoints
    Set and remove unconditional breakpoints.
  • Setting and Removing Conditional Breakpoints
    Set and remove conditional breakpoints.
  • Setting and Removing Request Breakpoints
    Set and remove request breakpoints before CICS commands, calls to DL/I, DB2, and SQL/DS, and calls to database software.
  • Setting and Removing Statement Trace Options
    Set and remove statement tracing and data monitoring for COBOL programs.
  • Setting and Removing Replacement Options
    Dynamically change CICS resources: programs, files, transient data queues, temporary storage.
  • Setting and Removing Protection Options
    Bypass CA InterTest for CICS rules that protect main storage, the CSA, and load modules.
  • Setting and Removing Special Options
    Modify monitoring rules (for example, prevent a program from updating a file, allow a program to branch to another program, limit the number of times a program is monitored).
  • Setting and Removing Composite Support
    Provide symbolic support for a program that consists of separately compiled modules.
  • Status Display
    Display the monitoring status of a program, transaction, or terminal.
  • Utility Options
    Display the contents of CA InterTest for CICS tables and files, and reset monitoring for a recompiled program.
  • System-Wide Options
    Request monitoring options on a system-wide basis.
  • Resume Task Execution
    Resume execution of a task stopped at a breakpoint.
Access the Monitoring Command Builder Main Menu
To display the Monitoring Command Builder main menu (the Function Selection Menu), enter
CNTL
on a clear screen, or enter
CNTL
on the command line of any source listing, detailed breakpoint, or CORE screen.
The Function Selection Menu
The Function Selection screen is the main menu for the Monitoring Command Builder. This menu lists the different CNTL functions detailed later.
If you select this function:
Also enter this:
10 through 22
In second field, enter S or R to specify SET or REMOVE. If left blank, it defaults to S.
10, 13, 16, 20, 21, 22, 24, or 30
Enter the program names, transaction codes, or terminal names. Specify from one to six programs, one to nine transactions, or one to nine terminals, but you cannot combine different types of entries. Specify .ALL to indicate all programs, transactions, or terminals. Also specify .OPTIONS in the Program Names field to set options for all programs. Optionally, specify a CICS user ID, such as MARY01, or .ANY to override the user ID default.
11, 12, 14, 15,or 23
In the Program Names field, enter one program name. Optionally, specify a CICS user ID, such as MARY01, or .ANY to override the user ID default.
31, 32, or 33
Do not specify program names, transaction codes, terminal names, or a user ID value.
If a program is stopped at a breakpoint and you type
CNTL
in the command line to access the Function Selection Menu, CA InterTest for CICS displays the name of the monitored entry (program, transaction, or terminal) on this screen.
When you have entered all the necessary information, press
Enter
. In most cases, a second screen opens. If you have specified multiple programs, transactions, or terminals, the names of all the entries display on subsequent screens.
When you
set
breakpoints, replacement, protection, special options, or composite support, you automatically set monitoring for the programs, transactions or terminals that you specify. So, for example, it is not necessary to set monitoring and set breakpoints; setting breakpoints accomplishes both functions.
However, when you
remove
breakpoints, replacement, protection, special options, or composite support, you do not remove monitoring for the programs, transactions, or terminals that you specify. Monitoring remains in effect until you explicitly instruct CA InterTest for CICS to remove monitoring.
Generic Specification of Programs, Transactions, or Terminals
When you set monitoring or monitoring options for a specific program, transaction, or terminal, CA InterTest for CICS creates an entry for that program, transaction, or terminal in the monitoring table. Also set monitoring or monitoring options generically by specifying asterisks, *, and plus signs, +, to replace characters in a program name, transaction code, or terminal name. These specifications are interpreted according to the rules for the CICS CEMT transaction.
  • An asterisk specifies any number of characters, including no characters. Specify more than one asterisk in a program name, transaction code, or terminal name. Do not, however, specify an asterisk by itself.
  • A plus sign specifies just one character in a particular position. Specify more than one plus sign in a name or code. Do not, however, specify a plus sign by itself.
  • Combine asterisks and plus signs.
Examples
Here is how the following specifications are processed:
  • ABC*
    Specifies all names or codes that begin with ABC, including ABC.
  • *ABC
    Specifies all names or codes that end with ABC, including ABC.
  • AB*C
    Specifies all names or codes that begin with AB and end with C with an unspecified number of characters in the middle.
  • ABC+
    Specifies all four-character names or codes that begin with ABC followed by any one character.
  • +ABC
    Specifies all four-character names or codes that begin with any character followed by ABC.
  • AB+C
    Specifies all four-character names or codes that begin with AB followed by any one character and C.
  • AB+C*
    Specifies all names or codes that begin with AB followed by one character, C, and an unspecified number of characters.
Hierarchy Rules for Monitored Entries
It is important to know the priorities CA InterTest for CICS observes if more than one entry in the monitoring table applies to the same program.
  • A specific or generic program entry overrides a transaction entry, a terminal entry, and an .ALL specification
  • A transaction entry overrides a terminal entry and an .ALL specification
  • A terminal entry (specific or generic) overrides an .ALL specification
Example
Suppose you specify monitoring options for program ABC1 and different options for transaction TRN1. ABC1 executes as part of that transaction. When ABC1 executes, the options specified for ABC1 override the options specified for TRN1. Similarly, it is important to understand the priorities CA InterTest for CICS observes when a program, transaction, or terminal is specifically and generically declared for monitoring. A specific entry overrides a generic entry
except
when you request Status Display. In this case, the generic specification takes precedence.
Suppose you specify monitoring options for program ABC1 and different monitoring options for program ABC*. The options specified for ABC* affect all programs whose names begin with ABC except for program ABC1 (and any other programs beginning with ABC that have their own entries in the monitoring table). Monitoring for ABC1 is controlled by the specific entry for that program. However, if you request a status display for program ABC*, you will get monitoring status reports for all programs that begin with ABC, including program ABC1 that has a separate monitoring table entry.
PF Keys
Exit from the Function Selection Menu by pressing a PF key. Most of these PF keys are also in effect on other Monitoring Command Builder screens. The following bullets describe the function of each PF key.
  • PF1 or 13
    Initiates the CA InterTest for CICS online help facility.
  • PF2 or 14
    Unassigned
  • PF3 or 15
    Terminates the Function Selection Menu screen and returns to the active breakpoint, if appropriate. Pressing Clear does the same thing.
  • PF4 or 16
    Returns to the source listing display facility.
  • PF5 or 17
    Unassigned
  • PF6 or 18
    Unassigned
  • PF7
    Unassigned
  • PF8
    Displays your previous CNTL Monitoring Command Builder screen with the specified data.
  • PF9 to end
    Unassigned
Monitoring
Set and remove monitoring for programs, transactions, or terminals directly from the Function Selection Menu. Specify function
10
,
S
or
R
, and the program names, transaction codes, or terminal names, and press Enter. For more information, see Function Selection Menu. This is the only screen you need to complete.
You can set a non-interactive monitoring session using CNTL options. For more information, see TFL Set Non-Interactive Monitoring.
Set Monitoring
When you set monitoring for a:
  • Program
    CA InterTest for CICS detects and prevents errors
    before
    they occur. That means monitored programs will not abend or commit storage violations. CA InterTest for CICS monitors the program from whatever terminal it executes, even if it executes as part of a non-terminal owning task. Use the replacement, protection, or special options screen if you want to restrict monitoring to a specific terminal.
  • Transaction
    CA InterTest for CICS monitors all of the transaction's programs.
  • Terminal
    CA InterTest for CICS monitors every program that executes at that terminal.
CA InterTest for CICS will not monitor programs that begin with the prefix DFH (IBM CICS programs) or IN25 (CA InterTest for CICS programs).
If you set monitoring for a transaction or terminal, and a program executing as part of that transaction or at that terminal is stopped at an automatic breakpoint, CA InterTest for CICS automatically creates an individual entry in the monitoring table for that program. This lets you set breakpoints and monitoring options specifically for that program. Similarly, if you specify .ALL in the Program Names field on the Function Selection Menu or if you specify a generic program name, CA InterTest for CICS creates an individual monitoring table entry for any program monitored under that entry when it stops at an automatic breakpoint.
Set the User ID for Monitoring
Monitoring is sensitive to CICS user IDs.
Remove Monitoring
Before you remove monitoring, you might want to produce a report of all CA InterTest for CICS monitoring activity to make sure other users are not currently testing the same programs. Press PF12
Status to produce a monitoring report.
When you remove monitoring, you also remove all breakpoints and monitoring options specified for that program, transaction, or terminal. A quick way of creating a new testing scenario for a program is to remove and then reset monitoring with different breakpoints and options.
Remember that you can also set monitoring by setting breakpoints, replacement, protection, special options, or composite support. However, if you remove breakpoints, options or composite support, monitoring
remains in effect
for the specified programs until you specifically instruct CA InterTest for CICS to stop monitoring.
Unconditional Breakpoints
When you set unconditional breakpoints, CA InterTest for CICS halts the program at the specified locations. CA InterTest also automatically monitors that program.
To set or remove unconditional breakpoints, specify function
11, S
or
R
, and the program name on the Function Selection Menu, and press Enter. For more information, see The Function Selection Menu.
Set Unconditional Breakpoints
Use the Breakpoint Locations screen to set unconditional breakpoints.
To set breakpoints, enter the following information:
Specify up to nine breakpoint locations in fields.
COBOL
For COBOL program, specify a paragraph name or data name, a statement number, or the hexadecimal displacement (offset) from the beginning of the program.
ASSEMBLER
For an Assembler program, breakpoint locations are Assembler labels, datanames, or offsets.
PL/I
For a PL/I program, breakpoint locations can be offsets or, if you have the PL/I symbolic option, PL/I labels or statement numbers.
Follow these rules when specifying information:
  • If you specify statement #1, CA InterTest for CICS sets a breakpoint at the first executable instruction in a COBOL Procedure Division, Assembler CSECT, or PL/I procedure.
  • COBOL statements can contain more than one verb. In specifying statement numbers, indicate the verb at which the breakpoint should occur. A statement number of nnn or nnn.0 indicates the first verb in the statement, nnn.1 indicates the second verb, nnn.2 indicates the third verb, and so on. For example, a statement number entered as 503.3 specifies a breakpoint at the fourth verb in statement number 503.
  • If you specify a COBOL or Assembler data name, breakpoints are set at every reference to that data name.
  • Enter an X in the All paragraph names field (COBOL) or All Assembler labels field to set breakpoints at all paragraph names or all labels.
Optional specifications:
  • If you set a breakpoint within a loop, specify a value in the Enter 'n' to stop only every n'th time field to set how often the program should be halted. For example, if you specify 3, the breakpoint occurs every third time the program passes through the loop.
  • Specify the ID of the terminal where the program must be executing for breakpoints to take effect. If you leave this field blank, it defaults to your current terminal. Enter .ANY to have breakpoints take effect at all terminals, even when the program executes without a terminal. Enter .NO to have breakpoints take effect only when the program executes without a terminal.
  • Specify the ID of the terminal to receive breakpoint displays. If you leave this field blank, it defaults to your current terminal. Enter .ANY to have breakpoint screens displayed at the terminal where the program is executing when breakpoints occur.
  • Specify the statement number of the indirect command that you want to invoke at the breakpoint you have set.
  • Specify the user ID who must be executing the program for the breakpoint to take effect. Valid entries are .ANY or a specific CICS user ID.
When you complete entering all the necessary information, press
Enter
.
Example
The following screen shows how to set unconditional breakpoints at four locations in the COBOL program COBDEMO.
CA InterTest MONITORING COMMAND BUILDER COBOL BREAKPOINT LOCATIONS 11 SET breakpoint locations for PROG=COBDEMO in any of the following fields: (For qualification by nested program name, specify 'ProgramID:Label') Para/Data return-transid________________ _______________________________ Names: _______________________________ _______________________________ _______________________________ _______________________________ Statement Numbers: 1____ 136__ 174.2 _____ _____ _____ _____ _____ Offsets: _____ _____ _____ _____ _____ _____ _____ _____ All paragraph names: _ Enter 'n' to stop only every n'th time: ____ Term ID (or .ANY or .NO) where breakpoints will take effect: ____ Term ID (or .ANY) that will receive the breakpoints: ____ Statement no. of indirect command(s) to be executed: ________ user ID (or .ANY) who will execute the program MARY01___
The information in the previous screen causes breakpoints to occur at:
  • Paragraph RETURN-TRANSID
  • Statement 1 (the beginning of the Procedure Division)
  • First verb in statement 136
  • Third verb in statement 174
Because the user ID field specifies a single user and the terminal ID fields are left blank, the breakpoints take effect at any terminal under which User MARY01 is executing COBDEMO.
Remove Unconditional Breakpoints
If you indicated that you want to remove unconditional breakpoints, the Remove Breakpoint Locations screen opens. COBOL, PL/I, and Assembler versions of the Breakpoint Locations screen are available.
To remove a breakpoint, specify the information that you originally defined on the Set Breakpoint Locations screen, or enter its ID number on the bottom of the screen.
The ID number appears on the Detailed Breakpoint display. Press
PF12
Status to request a status report for the program. This report lists the ID of each breakpoint.
To remove all unconditional breakpoints from a program, enter .ALL in the Para/Data field, and press
Enter
.
Conditional Breakpoints
When you set conditional breakpoints, CA InterTest for CICS halts the program at the specified locations
only
if a condition is met. Conditional breakpoints are very useful in isolating complex problems.
To set or remove conditional breakpoints, specify function
12, S
or
R
, and the program name on the Function Selection Menu, and press Enter. For more information, see The Function Selection Menu.
Set Conditional Breakpoints
First, CA InterTest for CICS displays the Conditional Locations screen.
This screen is similar to the screen used to specify unconditional breakpoints, and you should enter the information in the same way. For more information, see Set Unconditional Breakpoints.
A special feature lets you set a conditional breakpoint at
all
instructions.
To set conditional breakpoints:
  1. Enter an x in the All Instructions field to request this option. If you request the All Instructions option and set a variable-change breakpoint, the breakpoint takes effect whenever the value of the variable changes.
  2. Specify the breakpoint locations, and press
    Enter
    to display the Conditional Breakpoint screen.
  3. Specify the condition that must be satisfied for the breakpoint to take effect on the Conditional Breakpoint screen.
There are two versions of the Conditional Breakpoint screen: a simplified version for COBOL users, and a detailed version for PL/I and Assembler users and for those COBOL users who prefer this version.
On either version you, specify a condition in this format:
left side relational operator right side
Variable-Change Breakpoints
  • COBOL and Assembler users set a conditional breakpoint to take effect whenever the value of a variable changes. To do this, type
    x
    in the All Instructions field on the Conditional Locations screen.
  • COBOL users must then specify the variable name on the Conditional Breakpoint screen.
  • Assembler users must then specify the variable name on the Detailed Conditional Breakpoint screen, as discussed previously in The Detailed Conditional Breakpoint screen.
The value entered in the Operator field determines if the breakpoint occurs whenever the value of the variable changes (NE) or only when the value increases, decreases, or does not change. Whenever you re-execute the program, the initial value of the variable is reset to its value at the beginning of program execution.
Literal Formats
Specify four types of literals for the right side of the comparison:
  • Character
    Specify character literals for comparisons with any field except a COBOL data name defined as COMP or COMP-3. Enter the literal as
    C'character data', X'hexadecimal data'
    , or a combination of both. For example, C'ABC', X'0102', or C'ABC'X'0102'.
  • Packed
    Specify packed decimal literals for comparisons only with COBOL data names defined as COMP-3. Enter the literal as
    P'number'
    . The number can be preceded by a minus sign. For example, P'123' or P'-123'.
  • Halfword
    Specify halfword literals for comparisons with COBOL data names defined as COMP with a length of four, as in S9(4) COMP. Enter the literal as
    H'number'
    . The number can be preceded by a minus sign. For example, H'12' or H'-12'.
  • Fullword
    Specify fullword literals for comparisons with COBOL data items defined as COMP with a length of eight, as in S9(8) COMP. Enter the literal as
    F'number'
    . The number can be preceded by a minus sign. For example, F'100' or F'-100'.
Figurative Constants
Specify the following figurative constants for the right side of the comparison:
Valid Right Side Specifications for the Comparison
ZERO
ZEROS
ZEROES
numeric value 0
HIGH-VALUE
HIGH-VALUES
character value X' FF'
SPACE
SPACES
blank (X' 40' )
LOW-VALUE
LOW-VALUES
character value X' 00'
Example
The following sample screen shows how to set a conditional breakpoint in a COBOL program.
CA InterTest MONITORING COMMAND BUILDER CONDITIONAL BREAKPOINT Enter LEFT SIDE Data Name tolen ________________________________________________________ Enter OPERATOR (EQ, NE, GT, LT, GE, LE): lt Enter RIGHT SIDE Data Name ______________________________________________________________ OR Literal 80______________________________________________________________ _ Enter S to Drop monitoring on a true condition Press PF9 to go to complex conditional screen if necessary
  • The left side of the comparison specifies the data name TOLEN.
  • The relational operator is LT (less than).
  • The right side of the comparison specifies the literal 80.
This breakpoint takes effect only if the value in the data name TOLEN is less than 80. The breakpoint locations are all the instructions, as previously specified on the Conditional Locations screen.
Remove Conditional Breakpoints
When you specify that you want to
remove
conditional breakpoints, the Remove Conditional Locations screen opens.
The easiest way to
remove
a conditional breakpoint is from the Monitoring Status display. For more information, see Menus and Displays. To remove
all
conditional breakpoints from a program, enter .ALL in the Para/Data field, and press Enter.
The Detailed Conditional Breakpoint Screen
When Assembler and PL/I users want to specify conditional breakpoints complete the Conditional Locations screen and press
PF9
, the screen opens. COBOL users access this screen by pressing
PF9
from the COBOL Conditional Breakpoint screen.
Specify the following values:
  • The left side of the comparison must be an area of core. Enter information in
    one
    of these four fields:
    • Data name
    • Register
    • COBOL BLL cell
    • Area identified by a CORE keyword
  • The relational operator:
    • EQ for equal
    • NE for not equal
    • GT for greater than
    • LT for less than
    • GE for greater than or equal to
    • LE for less than or equal to
  • (Optional) The length of the left side or right side of the comparison. For more information, see Length of the Comparison.
  • The right side of the comparison, which is an area of core or a literal. Enter information in one of these five fields: a data name, a register, a COBOL BLL cell, an area identified by a CORE keyword, or a literal. For more information, see CORE Keywords and Literal Formats.
  • (Optional) Adjusts a CORE location by specifying offsets (displacements). Each offset must be preceded by one of the following operands:
    • +
    • -
    • @ (indirect addressing below the 16-megabyte line) % (indirect addressing above the 16-megabyte line; XA systems only)
    • Literals cannot be modified by offsets.
Length of the Comparison
Explicitly define how many bytes of the left side or right side specification should be compared. Certain storage locations have implicit lengths:
  • A register or COBOL BLL cell has an implicit length of four bytes
  • The storage locations referred to by the CORE keywords MXR, MXS, and TAL have implicit lengths of four bytes
  • The implicit length of a COBOL data name is its field length as defined in the DMAP
  • The length of a literal is the number of bytes it contains; any length specification is ignored
Define both left side and right side lengths for a packed decimal (COMP-3) comparison. For all other comparisons, define only one length. If you define both lengths, the smaller length is used.
The maximum permissible length for the left side or right side is 16 bytes for packed decimal data and 255 bytes for all other data types.
Literal Formats
For more information about specifying literals, see Figurative Constants.
CORE Keywords
Specify the following CORE keywords on the left side or right side of the comparison:
  • CMAR
    First byte of the EXEC CICS Communications Area for the task
  • CSA
    First byte of the CSA
  • CURR
    Next Assembler instruction to be executed
  • CWA
    First byte of the CWA
  • CWK
    First byte of the COBOL program's Working-storage
  • DSA
    First byte of the program's DSA
  • ITBE
    First byte of the next instruction to be executed
  • LCL
    First byte of the COBOL program's local-storage
  • MXR
    CA InterTest for CICS maximum CICS request counter (implicit length = 4)
  • MXS
    CA InterTest for CICS maximum storage counter (implicit length = 4)
  • OPFL
    First byte of the optional features List
  • PGM=*
    First byte of the monitored program
  • PREV
    Last Assembler instruction executed
  • R
    nn
    A register (
    nn
    is a decimal from 1 to 15) (implicit length = 4)
  • TAL
    CA InterTest for CICS tally fullword (implicit length = 4)
  • TERM=*
    First byte of the terminal table entry of the current terminal
  • TGT
    First byte of the COBOL TGT for the monitored task
  • TIOA
    First byte of the first TIOA of the task
  • TWA
    First byte of the TWA of the monitored task
Request Breakpoints
Set request breakpoints to halt a program prior to CICS commands and other program calls, such as calls to DL/I, DB2, or SQL/DS. Instruct CA InterTest for CICS to halt the program before every CICS command, or a type of CICS command, such as file control or program control commands. Specify that the program halts before specific commands, such as all READ or WRITE commands. Once the program halts, Use all of the CA InterTest for CICS facilities to inspect and modify main storage or auxiliary storage or to set additional options.
To set or remove request breakpoints:
  1. Specify function 13, S or R.
  2. Specify the program names, transaction codes, or terminal names on the Function Selection Menu, and press Enter.
CA InterTest for CICS displays the Request Breakpoint Selection menu. Enter an
x
next to the options you want to select.
You can specify any of the following breakpoints:
  • ALL commands
    The program halts prior to all CICS commands.
  • DL/I
    The program halts prior to all DL/I calls.
  • DB2
    The program halts prior to all calls to DSNHLI (for DB2 users) or prior to all calls to ARIPRDI (for SQL/DS users).
  • CALLS
    The program is halted prior to calls to software that CA InterTest has been instructed to recognize at installation time. A second screen, where you specify the calls, displays.
If you select a type of CICS command, CA InterTest for CICS displays a second screen. For example, if you select File Control, CA InterTest for CICS displays the File Control screen.
Place your cursor on a field and press F1 for a description of that field.
When you have entered all necessary information, press
Enter
.
To remove requested breakpoints, use the Monitoring Status display. Alternatively, enter the information exactly as you originally defined it.
Statement Trace Options
These options are unrelated to the backtrace facility.
Set Statement Trace options to save trace information for executed COBOL statements and to capture data values for those statements. Remove the Statement Trace options to delete the trace data.
To set or remove Statement Trace options, follow these steps.
  1. Specify function 16, S or R.
  2. Specify the program names, transaction codes, or terminal names on the Function Selection Menu, and press
    Enter
    .
The Statement Trace Options screen opens. For more information, see The Function Selection Menu.
Specify the following options on this screen. The equivalent option used in single-line commands is specified in parentheses.
  • Statement tracing (TRC)
    Instructs CA InterTest for CICS to save trace information for every executed COBOL statement.
  • Data monitoring (DM)
    Instructs CA InterTest for CICS to capture data values for every executed COBOL statement. If data monitoring is selected, statement tracing is automatically activated. In addition, a specific terminal ID or user ID is required.
  • Term ID (or .ANY or .NO) where trace options will take effect
    Specifies that the program be monitored and that Statement Trace options, if specified, take effect only when the program is executed at any terminal (.ANY), no terminal (.NO), or a specific terminal.
  • User ID (or .ANY) who will execute the program
    Specifies that the program be monitored and that Statement Trace options, if specified, take effect only when the program is executed by any user (.ANY) or a specific user (a CICS user ID).
Remove Statement Trace Options
To remove statement trace options, enter an
x
next to the options you want to remove. If you select statement tracing, data monitoring is also removed. Enter the terminal ID and user ID information exactly as you originally defined it.
Replacement Options
Set replacement options to dynamically change the names of CICS resources (programs, files, transient data queues, and temporary storage) specified in CICS CALLS by a monitored program. Remove the replacement options when you want the program to use the resources defined in the program.
Set Replacement Options
When you specify replacement options for a transaction, the resources are replaced in all its programs. When you specify replacement options for a terminal, the resources are replaced in all programs executing from that terminal.
To set or remove replacement options:
  1. Specify function 20, S or R,
  2. Specify the program names, transaction codes, or terminal names on the Function Selection Menu, and press
    Enter
    .
The Replacement Options screen opens. For more information, see The Function Selection Menu.
Specify five options on this screen. The equivalent option used in single-line commands is specified in parentheses on the following option list.
  • Replace program name (RPC)
    Allows a program name to be replaced. Specify the original program name and the new name.
  • Replace file name (RFC)
    Allows a file name to be replaced. Specify the original file name and the new name. The sample screen shown previously specifies that program COBDEMO use file TFILE instead of PFILE.
  • Replace TD queue name (RTD)
    Allows a transient data queue name to be replaced. Specify the original TD queue name and the new name.
  • TS selection mask; TS replacement mask (RTS)
    Allows a temporary storage ID to be replaced. Specify the original temporary storage ID in the TS selection mask field, and the new temporary storage ID in the TS replacement mask field. Specify both masks as eight bytes in either character (C'data') or hexadecimal (X'data') format. In the following example, STORAGE2 replaces STORAGE1 in all temporary storage requests issued by the program.
    TS selection mask: C'STORAGE1'
    TS replacement mask: C'STORAGE2'
  • Limit monitoring (TON)
    Specifies that the program be monitored and that replacement options, if specified, take effect only when the program executes at the current terminal (*), a specific terminal (termid), or without a terminal (.NO).
When you have specified the necessary information, press Enter.
Remove Replacement Options
To remove a replacement option, specify the information exactly as you entered it. To remove all replacement options of a specific type, enter
.ALL
in the appropriate field.
Example
To remove all file replacement options, enter
.ALL
in the Replace file name field.
Protection Options
This section describes protection options.
Set Protection Options
Set options to override the CA InterTest for CICS default protection rules for modifying main storage, the CSA, and load modules. Remove the protection options to reinstate the default protection rules.
Because the protection options can potentially damage your CICS system if misused, exercise caution in specifying them. These options are password protected unless your site has removed this restriction.
To set or remove protection options follow these steps.
  1. Specify function
    21, S or R
    .
  2. Specify the program name on the Function Selection Menu, and press Enter.
    The Protection Options screen displays. For more information, see The Function Selection Menu.
Specify the following options on this screen. In the descriptions, the command syntax equivalent for each monitoring option is specified in parentheses.
  • Bypass storage protection (BYP)
    Permits a specified section of program code to modify any area of main storage, issue SVC instructions, or issue BALR, BASSM. or BASR 14,15 or 14,14 instructions.
    • Specify the beginning and ending program addresses or program offsets. Specify addresses as six- to eight-hexadecimal digits, and offsets as one- to five-hexadecimal digits.
    • If you specify .ANY in the From field and an address or offset in the To field, CA InterTest for CICS suspends monitoring when any BALR, BASSM, or BASR 14,15 or 14,14 instruction passes control to the specified location. Monitoring resumes when the routine executed by the instruction returns control to the next byte after the instruction.
    • At a breakpoint, specify * in the From field and leave the To field blank to instruct CA InterTest for CICS to bypass the current instruction.
  • Unprotect CSA (CSA)
    Permits a program to modify areas in the CSA. Specify the offset and the length in hexadecimal.
  • Unprotect CWA (CWA)
    Permits a program to modify areas in the CWA. Specify the offset and the length in hexadecimal.
  • Unprotect main storage area (LET)
    Permits a program to modify a designated area of storage. Specify the beginning address as six to eight hexadecimal digits. Specify the length of the area in hexadecimal.
  • Unprotect load module (LET)
    Permits a program to modify a load module.
  • Protect main storage area (PRO)
    Prevents a program from modifying a designated area of storage not protected by CA InterTest. Specify the beginning address as six to eight hexadecimal digits. Specify the length of the area in hexadecimal.
  • Limit monitoring (TON)
    Specifies that the program be monitored and that the protection options, if specified, take effect only when the program executes at the current terminal (*), a specific terminal (termid), or without a terminal (.NO).
Remove Protection Options
To remove protection options, enter the information exactly as you originally defined it. To remove all options of a specific type, enter
.ALL
in the appropriate field.
Example
To remove all bypass storage protection options, enter
.ALL
in that field.
Special Options
This section discusses special options.
Set Special Options
Set special options to alter the CA InterTest for CICS standard monitoring procedures. Remove the special options to reinstate the default monitoring rules.
To set or remove special options, follow these steps.
  1. Specify function 22, S or R.
  2. Specify the program names, transaction codes, or terminal names on the Function Selection Menu, and press
    Enter
    .
The Special Options screen opens. For more information, see The Function Selection Menu.
Specify the following options on this screen. The equivalent option used in single-line commands is specified in parentheses.
  • Source Listing Breakpoint (SLB)
    Specifies that the Source Listing Breakpoint screen be displayed rather than the full breakpoint display screen. For more information, see Source Listing Facility for InterTest.
  • No file updating (NUP)
    Specifies that a monitored program not update any files. This option only affects VSAM and BDAM files; databases are unaffected.
  • Reentrancy check (RNT)
    Prevents a program from modifying its own code.
  • Follow monitoring (FOL)
    Instructs CA InterTest for CICS to continue monitoring a program even if it branches directly to another program (wild branch). All monitoring options remain in effect. Specify the following:
    • ON when control passes to a program that does
      not
      have a PPT entry
    • The name of the program when control passes to a program that has a PPT entry
    • NOPPT instead of ON to reduce overhead when a program often branches to a program that does not have a PPT entry
    • Note:
      Do not specify this option if control is passed to a program by a LINK or XCTL instruction. Such a program is monitored only if monitoring was specified for it.
  • Number of times to be monitored (MUS)
    Limits the number of times a program should be monitored.
  • Limit total size of CICS storage (MXS)
    Limits the amount of storage, including program storage, a program acquires.
  • Limit total number of CICS requests (MXR)
    Limits the number of requests a transaction issues. This option is useful when a program is in a loop that includes a CICS request.
  • Setting for Structure Display Format (SDF)
    Use this option to override, by program, the global default setting. Specify the following:
    • HEX to display data in hexadecimal / character format
    • DATA to display data in Structure Display Format
  • Set local automatic breakpoint (ABP)
    Activates the automatic breakpoint facility for a particular program, transaction, or terminal.
    Specify the terminal to receive automatic breakpoint displays.
    • Asterisk (*) routes the display to the current terminal
    • termid routes the display to a particular terminal
    • .ANY routes the display to all terminals
    • OFF instructs CA InterTest for CICS to abend the task instead of halting it at an automatic breakpoint
    This option is useful when you do not want the breakpoint display routed to the terminal where the program is running, or when the display cannot be routed to that terminal (for example, a non-terminal task or a task running on a non-3270 terminal). In those cases, specify the terminal to which breakpoint displays should be routed. The local automatic breakpoint option is also useful in a production environment when the global Automatic Breakpoint facility is disabled and you want to monitor a specific program, transaction, or terminal.
  • Limit monitoring (TON)
    Specifies that the program be monitored and that the special options, if specified, take effect only when the program executes at the current terminal (*), a specific terminal (termid), or without a terminal (.NO).
Remove Special Option
To remove special options, enter an
x
next to the options you want to remove, or enter the information exactly as you originally defined it.
Set and Remove Composite Support
The CA InterTest for CICS composite support feature lets you take advantage of all of the CA InterTest for CICS capabilities when you test and debug composite modules. A
composite module
is a load module defined in the PPT that consists of separately compiled or assembled parts brought together when the module is link-edited. The part of the composite module that receives control from CICS is referred to as the
main
program
; the remaining parts are referred to as
subprograms
. The main program and subprograms are written in the same or different languages.
Composite support lets you test and debug a subprogram as if it were a
separate
program. This means you set breakpoints and other monitoring options individually for any subprogram.
CA InterTest for CICS provides
full symbolic support
for the main program and subprograms if you provide that information when the programs are compiled or assembled.
Function 23 on the CNTL Function Selection Menu is one method of accessing the Composite Support screen. An alternative method of accessing this screen is from the ITST monitoring menus.
Indirect Commands
The CA InterTest for CICS indirect commands facility lets you define a set of commands that execute automatically or
indirectly
at a predetermined location in a monitored COBOL or PL/I program. These commands are invoked from an unconditional, conditional, or request breakpoint.
In effect, indirect commands are executed at breakpoints within your program just as other CA InterTest for CICS line commands issued from the Source Listing display, such as MOVE and GO, are used to alter the flow of your program's logic. The difference is that indirect commands are executed automatically without issuing a breakpoint display. Once the indirect commands are performed, your program continues to execute normally.
Indirect commands save you from having to recompile a program or manually correct an area of code every time it is encountered during a debugging session. With the indirect commands facility, you can:
  • Change the flow of control in your program
  • Test conditions based on specified variables
  • Change the value of specified variables
  • Create and execute commands as a group, like adding a new subroutine
  • Automatically resume execution of your program at the same or different location
  • Define abbreviations for variables with long names
    Indirect commands are
    not
    available for Assembler programs.
Indirect commands are not supported in a CICSPlex environment and they are not saved in the MLOG when session logging is turned on.
When to Use Indirect Commands
Indirect commands are used to correct the following sample program problems:
  • A variable is not being initialized during processing. Using indirect commands initialize the variable every time the program is run and continue execution without recompiling.
  • A new routine is needed in your program. Insert the code using indirect commands and continue executing your program without recompiling.
  • A section of code is bad. To continue executing or testing without recompiling, write and invoke indirect commands to direct CA InterTest for CICS to go around the bad source code or execute a new series of indirect command statements.
Step Overview
For users familiar with the CNTL menus, use Function 24 of the CNTL Function Selection Menu to access the indirect commands facility when you are coding the commands.
Status Display
Determine the monitoring status of one or more programs, transactions, or terminals by following these steps:
  1. Specify Function
    30
    .
  2. Specify the program names, transaction codes, or terminal names on the Function Selection Menu, and press
    Enter
    .
    If you specify multiple programs, transactions, or terminals, CA InterTest for CICS displays the monitoring reports in the order in which you specified the entries.
The status display accessed from the CNTL menu does not include the same formatting as the monitoring status report discussed in other areas of this documentation.
It is advisable to determine the monitoring status of a program, transaction, or terminal before altering it.
Example
The following screen shows a status report for the program COBDEMO.
CA InterTest for CICS Activity Report, 11:39 a.m at terminal L905 CICS Trace for InterTest internals is on. No currently monitored tasks found. Automatic BreakPoint feature is globally active. Automatic BreakPoint default terminal is not declared. CKPT intrval=00:10 hh:mm CKPT done at 11:37 a.m. COBDEMO Symbolic file is PROTDEM UBP offset= +01B44 id=56A7D208 at=#898 from=L903 to=L903 UBP offset= +016C2 id=B903CE24 at=#1 from=L903 to=L903 SLB terminal is L903 Source Listing Breakpoints are off. Listing view profile: Default. Singlestep no less than 002 statements. * Entry not active * End of Report * --------------------------------------------------------------------------------- PF1:Top PF7:Up PF8 or Enter:Down PF3 or Clear:End PF4:Refresh. Page 001
This report provides the following information:
  • Automatic Breakpoint feature ...
    The global ABP (Automatic Breakpoint) facility is active. This means monitored programs will receive breakpoint displays when an error triggers an automatic breakpoint.
  • Automatic Breakpoint default ...
  • There is no global ABP terminal.
  • CKPT interval
    The checkpoint recording facility is in effect. The interval between checkpoints is 30 minutes.
  • CKPT done
    The last checkpoint occurred at 9:45 a.m.
  • COBDEMO
    The next line identifies the program for which the status report was generated as COBDEMO.
  • lines following COBDEMO
    The rest of the report indicates the options currently active for COBDEMO. In this example, only Unconditional Breakpoints (UBP) are active for this program. For each breakpoint, the report provides the information shown in the following table.
    • offset=
      The breakpoint location is defined as a hexadecimal offset from the beginning of the program.
    • i
      d=
      hhhhhhhh
      The breakpoint ID number assigned by CA InterTest for CICS.
    • at=
      location
      The symbolic location specified when the breakpoint was set. A number preceded by a # sign refers to a statement number, except for #1, which refers to the first executable instruction.
    • from=
      termid
      The ID of the terminal where the program must be executing for the breakpoint to take effect.
    • to=
      termid
      The ID of the terminal that will receive the breakpoint display.
    Note:
    If you do not see the message, End of Report, the report is too long to fit on one screen. Press Enter to display more of the report.
  • *Entry not active*
    Indicates that CA InterTest for CICS is not currently monitoring the program.
Utility Functions
Use the utility functions to produce CA InterTest for CICS reports and to reset monitoring for a recompiled program.
To select utility functions, specify Function
31
on the Function Selection Menu, and press
Enter
. The Utility Options screen opens.
Specify the following functions on this screen. The equivalent function used in single-line commands is specified in parentheses.
  • List CA InterTest tables (LIST)
    Requests a list of all the programs, transactions, and terminals that CA InterTest for CICS was instructed to monitor or not to monitor. The report also lists the programs CA InterTest for CICS will monitor as a result of the FOL special option.
  • List programs in symbolic file (SYM)
    Requests a list of all the programs in the CA InterTest for CICS symbolic file. For each program, this report lists its date and time of compilation, the number of records it occupies in the file, whether it can be purged, and whether it was compiled with the LISTER option.
  • Global monitoring report (INQ)
    Requests a report of all CA InterTest for CICS monitoring activity.
  • List one program in symbolic file (SYM)
    Requests information for one program in the CA InterTest for CICS symbolic file. It lists the date and time of compilation, the number of records it occupies in the file, whether it can be purged, and whether it was compiled with the LISTER option.
  • New program copy (NEW)
    Resets symbolically specified breakpoints and other monitoring options for a recompiled program. Also resets the entry in the PPT Table to the program's new library address.
The reports produced by the options LIST, SYM, and INQ might be too long to fit on one screen. Press
Enter
to display more of the report. To write a report to a transient data queue, enter the name of the TD queue.
Set SystemWide Options
Set certain options on a system-wide basis. Specify Function 32 on the Function Selection Menu, and press Enter. The System-Wide Options screen opens.
Specify the following options on this screen. Specify in parentheses the equivalent option used in single-line commands. Enter
ON
to set an option and
OFF
to remove it.
  • Automatic breakpoint (ABP)
    Sets the automatic breakpoint facility for the entire system; the default. Breakpoint displays are routed to the terminal where the program is running. Specify a terminal ID to indicate where breakpoint displays should be routed for non-terminal attached tasks and for tasks executing from non-3270 terminals.
    If you specify OFF for the ABP option, you might want to use the Special Options screen (Function 22) to set the local automatic breakpoint option for one or more programs. The local automatic breakpoint option overrides the system automatic breakpoint option.
  • Global logging (GLOG)
    Requests global logging of CA InterTest for CICS activity: most CNTL commands and all changes to main storage.
  • System-wide monitoring (ALL)
    Instructs CA InterTest for CICS to monitor all application programs in the system, except those with the prefix DFH (IBM CICS programs) or IN25 (CA InterTest for CICS programs).
    Specify only one of the following two options at one time. To set both facilities, return to the Function Selection Menu and specify Function 32 again.
  • Purge breakpointed tasks (PURGE)
    Instructs CA InterTest for CICS to periodically purge tasks halted at a breakpoint for longer than the specified interval. The first purge occurs when the option is specified. Subsequent purges occur at the end of the interval, specified in hours and minutes in this format hhmm. The minimum time interval is 20 minutes.
  • Checkpoint CA InterTest (CKPT)
    Instructs the checkpoint recording facility to record periodically the status of CA InterTest for CICS monitoring so that you can use the restart feature. The first checkpoint occurs when the option is specified. Subsequent checkpoints occur at the end of the interval, specified in hours and minutes in this format hhmm. The minimum time interval is 10 minutes.
    These options are password protected unless your site has removed this restriction.
Resume Task Execution
When a task is halted at a breakpoint, request that execution of the task resume. Specify Function 33 on the Function Selection Menu and press
Enter
. For more information, see The Function Selection Menu.
The Monitoring Command Builder - Resume Task Execution screen displays. For detailed help on any of the fields on this panel, position your cursor in the field and press F1.
Example
The following screen shows how to specify task resumption.
This screen specifies that the task:
  • Resume at a new location: TASK-NUMBER-FOR-MSG.
  • Execute three COBOL verbs before halting again.
CA InterTest MONITORING COMMAND BUILDER RESUME TASK EXECUTION 33 Press ENTER without options to resume execution of the breakpointed task _____ OR enter one or more of the following options: To RESUME EXECUTION at a different location, enter ONE new location: COBOL paragraph, Assembler or PL/1 label: tasknumberformsg____________ COBOL or PL/1 statement number: _____ Offset: _____ To MOVE this breakpoint enter ONE new location, OR enter X to DISABLE it: COBOL paragraph, Assembler or PL/1 label: _______________________________ COBOL or PL/1 statement number: _____ Offset: _____ To AUTO STEP, enter #n for COBOL verbs or PL/1 STMTS or n for instrucs: #3___ with a n second WAIT between breakpoints:____ to HALT at a CALL, enter XOR after n steps are reached:____ To take a DUMP before continuing, enter a 1 to 4 digit dump code: ____ To ABEND transaction, enter dump code or XXXX if no dump is desired: ____
CNTL Monitoring Commands and Options
Enter single-line commands instead of using menus and screens. Entering commands directly is often faster and more efficient for experienced users. The CA InterTest for CICS CNTL transaction performs all monitoring functions. This topic teaches you which CNTL single-line commands you use to specify monitoring, monitoring options, and system-wide options. For example, to set monitoring for the program COBDEMO when executed by the user ID BARNEY1, and also set a breakpoint at the beginning of the program, enter the following single command from CICS:
CNTL=ON,PROG=COBDEMO,USR=BARNEY1,UBP=#1
CNTL Commands at a Glance
The following table indicates the functions you specify with commands and, where appropriate, the equivalent selections on the Primary Option menu, Breakpoint menu, and CNTL Function Selection Menu.
CNTL Command
Description
Menu Path
CNTL Function
START, END
Initializes and terminates CA InterTest for CICS.
Not available
Not available.
RESTART
Restarts CA InterTest for CICS.
Not available
Not available.
ON, OFF
Sets and removes monitoring.
Primary
2.1, 2.2, 2.3
10
ON, OFF
Sets and removes monitoring options.
Primary
2.1, 2.2, 2.3
11 to 23
OFFALL
Removes ALL monitoring options for ALL programs/transactions/terminals set by a Userid or Terminal
Not available
Not available
EXCL, INCL
Excludes programs from monitoring and ends program exclusion; applies to all CICS user IDs.
Not available
Not available.
GO
Resumes task execution.
Breakpoint 4
33
GO
Abends a task.
Breakpoint 3
33
INQ, LIST
Produces CA InterTest for CICS reports.
Type STATUS
30 and 31
NEW
Loads a new copy of a program.
Primary
2.1, 2.2, 2.3
31
ABP, GLOG, CKPT,PURGE
Sets system-wide options.
Primary 2.6
32
EXEC
Executes a module of CNTL commands.
Not available
Not available.
MLOG
Records a monitoring session so that it can be repeated.
Primary 2.7
Not available
For more information about specifying CNTL Monitoring Options, see CNTL Monitoring Options.
CNTL Command propagation in a CICSPlex Environment
For CICSPlex environments using the CA InterTest for CICS CICSPLEX=YES installation option, all CNTL functions that are checkpointed are propagated to all CICSPlex family members on startup (CNTL=START) or restart (CNTL=RESTART). The following table summarizes which CNTL commands are propagated and which are not.
Commands Propagated to All Family Members
Commands Not Propagated
Comments
CNTL=ABP
CNTL=ADD
CNTL=CKPT
CNTL=DUMP
CNTL=END, {SCOPE=GLOBAL}
Propagated if SCOPE=GLOBAL is specified.
CNTL=EXCL
CNTL=FOL
CNTL=GLOG
CNTL=INCL
CNTL=ITTRACE
CNTL=NEW
CNTL=OFF
CNTL=ON
CNTL=OFF,ALL
CNTL=EXEC
Commands in the module are propagated if they are eligible for propagation.
CNTL=GO
CNTL=INQ
CNTL=LIST
CNTL=MENU
CNTL=MLOG
CNTL=PURGE
CNTL=VRPT
CNTL Command Syntax
CNTL command syntax uses the following notational conventions:
  • Uppercase words (such as CNTL) are CA InterTest for CICS keywords that must be entered exactly as shown
  • Lowercase words (such as promid) represent user-supplied information and should be replaced with the appropriate entries.
  • Information in brackets is optional and can be omitted
The following list contains the terms used in command syntax for which you must substitute the appropriate information.
  • promid
    Identifies one or more programs, transactions, or terminals. Use one of the following formats:
PROG=program PROG=(prog1,...,prog9) TRAN=trancode TRAN=(tran1,...,tran9) TERM=terminal TERM=(term1,...,term9) PROG=.ALL to specify the entire system
An
* replaces promid for the monitoring table entry currently at a breakpoint at your terminal.
  • progname
    Identifies a program.
  • locn
    Identifies a program location. Specify a location in one of the following ways:
    • One- to five-digit hexadecimal displacement (offset) from the beginning of the program
    • Six- or eight-digit hexadecimal address
    • A COBOL paragraph name enclosed in single quotes
    • A COBOL or PL/I statement number preceded by a # sign
    • A PL/I or Assembler label enclosed in single quotes
  • options
    Indicates one or more CNTL monitoring options. Separate multiple options with commas.
Enter CNTL commands directly on a clear screen or on the command line of a source listing, breakpoint, or CORE display.
Generic Specification of promid
Specify asterisks, *, and plus signs, +, to replace characters in
promid
in the following CNTL commands:
CNTL=ON,... CNTL=OFF,... CNTL=EXCL,... CNTL=INCL,... CNTL=INQ,...
An asterisk, *, specifies any number of characters, including no characters.
These specifications are interpreted according to the rules for the CICS CEMT transaction.
Examples
To specify all programs that start with ABC, including program name ABC, enter:
PROG=ABC*
To specify all programs that end with ABC, including program name ABC, enter:
PROG=*ABC
To specify all programs that start with AB and end with C and all those that could have an unspecified number of characters in the middle, enter:
PROG=AB*C
Specifies more than one asterisk in a promid. Do not specify an asterisk by itself: PROG=* because it is invalid.
To specify all four-character program names that begin with ABC followed by any one character, enter:
PROG=ABC+
A plus sign, +, specifies only one character in a particular position.
To specify all four-character program names that begin with any character followed by ABC, enter:
PROG=+ABC
To specify all four-character program names that begin with AB followed by any one character and C, enter:
PROG=AB+C
Specify more than one plus sign in a promid. Do not specify a plus sign by itself: PROG=+ because it is invalid.
To specify all programs that begin with AB followed by one character, C, and an unspecified number of characters, enter:
PROG=AB+C*
Combine asterisks and plus signs.
Hierarchy Rules for Monitored Entries
It is important to know the priorities CA InterTest for CICS observes if more than one entry in the monitoring table applies to the same program.
  • The PROG=.OPTIONS specification overrides all other specifications
  • A program entry (specific or generic) overrides a transaction entry, a terminal entry, and an .ALL specification
  • A transaction entry (specific or generic) overrides a terminal entry and an .ALL specification
  • A terminal entry (specific or generic) overrides an .ALL specification
  • A specific user ID overrides an .ANY specification
Example
Suppose you specify monitoring options for program ABC1 and different options for transaction TRN1. ABC1 executes as part of that transaction. When ABC1 executes, the options specified for ABC1 override the options specified for TRN1.
Similarly, it is important to understand the priorities CA InterTest for CICS observes when a program, transaction, or terminal is specifically and generically declared for monitoring. In this case, a specific entry overrides a generic entry except when you issue the command CNTL=INQ,promid, where the generic specification takes precedence.
Example
Suppose you specify monitoring options for program ABC1 and different monitoring options for program ABC*. The options specified for ABC* affect all programs whose names begin with ABC except for program ABC1 (and any other programs beginning with ABC that have their own entries in the monitoring table). Monitoring for ABC1 is controlled by the specific entry for that program. However, if you specify CNTL=INQ,PROG=ABC*, you get monitoring status reports for all programs that begin with ABC, including programs such as ABC1, which have separate monitoring table entries.
Initialize and Terminate CA InterTest for CICS
To initialize CA InterTest for CICS, enter:
CNTL=START
To terminate CA InterTest for CICS, enter:
CNTL=END
This command terminates CA InterTest for CICS for all users and could be password protected.
Restart CA InterTest for CICS
Use the CNTL=RESTART command to restart CA InterTest for CICS. The command has the following syntax:
CNTL=RESTART,TODAY=ONLY,NOWAIT
The command has the following parameters:
  • TODAY=ONLY
    (Optional) Specifies that CA InterTest for CICS only restarts if the checkpoint occurred on the same day
  • NOWAIT
    (Optional) Suppresses displays of messages and makes the restart much faster
When CA InterTest for CICS is restarted from a sequential terminal, it ignores all input records following the RESTART command until it finds a record with this command:
CNTL=DUMMY
This terminates the CNTL transaction and permits the system to execute transactions from subsequent input records. However, if the restart is unsuccessful, the CNTL transaction terminates and all input records that follow the RESTART command are executed as usual by CICS.
Set and Remove Monitoring
To set monitoring, enter:
CNTL=ON,promid
To set monitoring for all programs and all users, enter:
CNTL=ON,PROG=.ALL,USR=.ANY
To set monitoring for all programs executed by the user whose CICS user ID is BARNEY1, enter:
CNTL=ON,PROG=.ALL,USR=BARNEY1
To remove monitoring, enter:
CNTL=OFF,promid
Examples
To turn on monitoring for program COBDEMO enter:
CNTL=ON,PROG=cobdemo
To turn off monitoring for programs COBDEMO and PAYPROG, enter:
CNTL=OFF,PROG=(cobdemo,payprog)
Automatic Creation of Monitoring Table Entries
If you set monitoring for a transaction or terminal and a program executing as part of that transaction or at that terminal is stopped at an automatic breakpoint, CA InterTest automatically creates an entry in the monitoring table for that program. This enables you to set breakpoints and monitoring options for that individual program. Similarly, if you specified CNTL=ON,PROG=.ALL or you specified a generic program name, CA InterTest for CICS creates an individual monitoring table entry for any program monitored under that entry that CA InterTest for CICS stops at an automatic breakpoint.
Set and Remove Monitoring Options
To set monitoring options, enter:
CNTL=ON,promid,options or CNTL=ON*,options
To set system-wide default monitoring options, enter:
CNTL=ON,PROG=.OPTIONS,USR=.ANY,options
Options specified on a system-wide basis take effect for all programs CA InterTest for CICS monitors.
Specify only the following options on a system-wide basis: ABI, CSA, FOL, ICT, LET, MXR, MXS, NUP, PRO, RFC, RNT, RPC, RTD, RTS, SLB, STR, and TRC.
To remove monitoring options, enter:
CNTL=OFF,promid,options OR CNTL=OFF*,options
Examples
To set the Follow option for the task currently at a breakpoint at your terminal, enter:
CNTL=ON*,FOL=ON
To set the No Update option for all monitored tasks, enter:
CNTL=ON,PROG=.OPTIONS,NUP=ON
To remove the unconditional breakpoint at statement number 1 for program COBDEMO, enter:
CNTL=OFF,PROG=cobdemo,UBP=#1
Set and Remove ALL Monitoring Options Set by a User ID or Terminal
To remove ALL monitoring options set by a specific User ID or for a specific Terminal, enter:
CNTL=OFF,ALL,USR=userid or CNTL=OFF,ALL,TTR=termid,FTR=termid
TTR= and FTR= must specify the same terminal ID.
Use this command with
caution
because it removes monitoring options for more than one program or transaction. This command is also passed to the CNTL transaction as data on a CICS START command and could be used by an installation's AutoInstall exit when a terminal signs off to
automatically
remove all CA InterTest for CICS breakpoints set by the terminal or user ID.
Exclude Programs from Monitoring
To exclude a program from monitoring, enter:
CNTL=EXCL,promid
To remove the monitoring exclusion set by the CNTL=EXCL command, enter:
CNTL=INCL,promid
INCL and EXCL are not sensitive to the monitoring user ID.
Examples
To exclude all of transaction PYRLs programs from monitoring, enter:
CNTL=EXCL,TRAN=PYRL
To remove program PAYROLL1 from the exclusion list so it is again eligible for
monitoring, enter:
CNTL=INCL,PROG=payroll1
Resume Task Execution
To resume task execution at a breakpoint, enter:
CNTL=GO,TASK=taskid,C[,options]
  • taskid
    Represents the number of the task at a breakpoint. Use the CNTL=INQ command to determine the
    taskid
    .
    C
    instructs CA InterTest for CICS to continue execution.
To resume execution of the task currently at a breakpoint at your terminal, enter:
CNTL*C[,options]
To resume task execution after taking a transaction dump, enter:
CNTL=GO,TASK=taskid,Ddddd[,options]
  • D
    dddd, dddd
    Specifies a four-character transaction dump code.
Specify the following options with the CNTL commands for resuming execution:
AT=locn
or
AT=X GO=locn NOBREAK S=#nnn[,I=nn][,N=CALL/xxxx]orS=nnn[,I=nn][,N=CALL/xxxx]
AT
=
locn
moves the current breakpoint to a different location.
AT
=
X
disables the breakpoint.
GO
=
locn
specifies the location at which the task should resume execution. For more information, see GO=Element Limitation.
NOBREAK
resumes execution from the current statement ignoring all preset breakpoints and indirect commands until the task either abends or runs to normal completion. Use the NOBREAK option on:
CNTL*C
or
CNTL=GO, TASK=xxxxx, C
S=#nnn[,I=nn][,N=CALL/xxxx]
instructs CA InterTest for CICS to halt program execution after
nnn
COBOL verbs or PL/I statements are executed.
  • S=
    nnn
    [,I=
    nn
    ][,N=CALL/
    xxxx
    ]
    instructs CA InterTest for CICS to halt program execution after nnn machine instructions are executed.
  • I=
    nn
    instructs CA InterTest for CICS to repeat the single-stepping after pausing for
    nn
    seconds
  • N=CALL halts automatic single-stepping at a CALL or CICS commands
  • N=
    xxxx
    halts automatic single-stepping after a specified number (1-9999) of steps
S=1 is specified as S.
Examples
To specify that task 12345 resume at COBOL paragraph name TASK-NUMBER-FOR-MSG, enter:
CNTL=GO,TASK=12345,C,GO=`task-number-for-msg'
To specify that the task currently at a breakpoint at your terminal resume at statement number 142 and that the program execute five COBOL verbs or PL/I statements before being halted, enter:
CNTL*C,GO=#142,S=#5
To specify that task 12345 resume execution after taking a dump and that the current breakpoint be disabled, enter:
CNTL=GO,TASK=12345,Dhelp,AT=X
The transaction dump code is HELP.
To specify that task 777 resume execution at indirect command sequence number 10, enter:
CNTL=GO,TASK=777,C,EXEC=0010
GO= Element Limitation
When changing the execution sequence of a high level program, especially COBOL or PL/I, you must take responsibility for securing proper
addressability
of the data that will be processed in the piece of logic specified by GO= element.
In COBOL, before you force a branch (GO TO) to the routine using GO= element, the BLLs and their corresponding registers must contain correct addresses. Accomplish this with CORE commands, especially the =SET element of the CORE command. Use symbolic names of BLL cells. The BLL cells are related to their data structures in the Data Division Map (DMAP) of the COBOL listing, while the related registers are found in the register assignment section of the memory map.
SERVICE RELOAD statements in the COBOL program are necessary to notify the COBOL compiler that, at a specific time, the registers must be reloaded when the address of the base of a certain data structure changes. If you force a branch (GO TO) to the intended routine using the GO= element and, in the process, you cross the boundaries of SERVICE RELOAD, then it is necessary to set the addresses.
In PL/I, you not only must secure the proper addressability of data, but also remain within the same logical level (such as the same DO block or called procedure). Going to another logical level requires going through all intermediate epilogues and prologues.
Abend a Task Stopped at a Breakpoint
To abend a task
with
or
without
a transaction dump, enter:
CNTL=GO,TASK=taskid,Adddd[,options]
  • taskid
    Represents the number of the task at a breakpoint. Use the CNTL=INQ command to determine the taskid.
  • Adddd dddd
    Specifies a four-character transaction dump code. Replace
    dddd
    with
    XXXX
    to abend the task
    without
    a dump and disable exits.
A dump code of XXXX is not allowed for tasks in a MRO session. Specify A by itself to abend the task
without
a dump and enable the exits.
Specify the following options:
AT=locn or AT=X
AT=
locn
moves the breakpoint to a different location
AT=X disables the breakpoint
Examples
To abend task number 54321 with a dump and a transaction dump code of DMP1, enter:
CNTL=GO,TASK=54321,Admp1
To abend task number 54321 without a dump, enter:
CNTL=GO,TASK=54321,AXXXX
To abend the current task with a dump and move the current breakpoint to statement number 128, enter:
CNTL*Admp1,AT=#128
To abend the current task without a dump, enter:
CNTL*AXXXX
How to Produce CA InterTest for CICS Reports
To produce a monitoring status report, enter:
CNTL=INQ,promid[,TODEST=destid]
To produce a monitoring status report for the task currently at a breakpoint at your terminal, enter:
CNTL?
To produce a system-wide monitoring report, enter:
CNTL=INQ[,TODEST=destid]
To display the contents of CA InterTest for CICS monitor tables, enter:
CNTL=LIST[,TODEST=destid]
To display the entire contents of the CA InterTest for CICS symbolic file, enter:
CNTL=INQ,SYM=ALL[,TODEST=destid]
To display information for one program in the CA InterTest for CICS symbolic file, enter:
CNTL=INQ,SYM=progname[,TODEST=destid]
  • destid
    Represents the transient data destination. If omitted, the report displays on your terminal screen.
Examples
To request a monitoring status report that displays on your terminal screen for program COBDEMO, enter:
CNTL=INQ,PROG=cobdemo
To request a monitoring status report for all programs that is routed to the CSSL transient data queue, enter:
CNTL=INQ,TODEST=CSSL
To request a report listing information on all programs in the symbolic file that is routed to the CSSL transient data queue, enter:
CNTL=INQ,SYM=ALL,TODEST=CSSL
Load a New Copy of a Program
To load a new copy of a program, reset symbolic breakpoints, and reset the entry in the PPT to the program's new library address, enter:
CNTL=NEW,PROG=progname
The specified program is declared for monitoring before any breakpoints are reset. Monitoring and breakpoints are reset for all user IDs. If you have breakpoints set for
Statement #
or
Offset
, then you should first deactivate monitoring for the program, issue the NEW copy, then reset your breakpoints to insure they are in sync with the new program version.
Example
To load a new copy of program COBDEMO.
CNTL=NEW,PROG=COBDEMO
Specify optionally a SYM=.NOASK parameter. Doing so causes InterTest Symbolic File Date Checking module to bypass ASKing the terminal operator to select a symbolic file member when a date or time mismatch is detected for a COBOL or PL/I module being NEW copied or when an Assembler module being new copied has more that one member in the symbolic files.
This parameter should be used with
caution
as it forces CA InterTest for CICS to use the first symbolic file member it finds for a program being NEW copied when breakpoints are reset after the new module is copied.
Log a Monitoring Session
When you monitor a program, you can log, or record, the monitoring session and save it to PROTMLOG. You can then use this file to repeat your monitoring session later.
All monitoring session commands are applied to the user ID and terminal that issue the commands.
Indirect commands are not saved in the MLOG when session logging is turned on.
  • To start recording a new monitoring session, enter:
    CNTL=MLOG,START,
    name
    [,
    description
    ]
    • name
      Specifies a session name.
      Limits:
      1 to 8 characters
    • description
      (Optional) Describes the session.
      Limits:
      0 to 35 characters
    When you issue the START command, the active recording session is indicated by a flashing REC on the Source Listing Display screen.
  • To stop recording and save the current session, enter:
    CNTL=MLOG,STOP
    When you issue the STOP command, the flashing REC disappears from the Source Listing Display screen.
  • To cancel the current session and delete all entries that were recorded since the START command was issued, enter:
    CNTL=MLOG,CANCEL
    When you issue the CANCEL command, the flashing REC disappears from the Source Listing Display screen.
  • To delete the entries from an existing session, enter:
    CNTL=MLOG,DELETE,
    name
    • name
      Specifies the session.
      Limits:
      1 to 8 characters
  • To load an existing session, enter:
    CNTL=MLOG,LOAD,
    name
    • name
      Specifies the session.
      Limits:
      1 to 8 characters
      You can only load saved sessions. Active sessions cannot be loaded.
Set System-Wide Options
To activate the automatic breakpoint facility for the entire system, enter:
CNTL=ABP,ON,termid
Breakpoint displays are routed to the terminal where the program is running. Specify a terminal ID to indicate where breakpoint displays should be routed for non-terminal attached tasks and for tasks executing from non-3270 terminals.
The delivered default is to activate the global automatic breakpoint facility when CA InterTest for CICS is initialized.
To deactivate the global automatic breakpoint facility, enter:
CNTL=ABP,OFF
If you deactivate the global automatic breakpoint facility, set the local Automatic Breakpoint option for one or more programs, transactions, or terminals. The local Automatic Breakpoint option overrides the system automatic breakpoint facility.
To log all CNTL commands (except INQ and LIST) and all changes made to main storage, enter:
CNTL=GLOG,ON
To de-activate global logging of CA InterTest for CICS commands, enter:
CNTL=GLOG,OFF
To activate checkpointing so that the status of the CA InterTest for CICS monitoring is periodically monitored so that you can use the restart feature, enter:
CNTL=CKPT,INTRVAL=hhmm
The first checkpoint occurs when the option is specified. Subsequent checkpoints occur at the end of the interval, specified in hours and minutes. The time interval must be at least ten minutes,
To terminate checkpointing, enter:
CNTL=CKPT,OFF
To periodically purge all tasks waiting at a breakpoint, enter:
CNTL=PURGE,INTRVAL=hhmm
The first purge occurs when the option is specified. Subsequent purges occur at the end of the interval, specified in hours and minutes. The time interval must be at least 20 minutes
To purge all tasks waiting at a breakpoint at once, enter:
CNTL=PURGE,ALL=ONCE
To deactivate the purge facility, enter:
CNTL=PURGE,OFF
Example
To activate checkpointing with the first checkpoint occurring immediately and subsequent checkpoints occurring at 50 minute intervals, enter:
CNTL=CKPT,INTRVAL=0050
Execute a Module of CNTL Commands
Assemble modules containing CNTL commands by using the CA InterTest for CICS PROMMAC macros.
For more information about CNTL commands, see Start CA InterTest for CICS.
After the product is activated, enter the following command to execute the commands in the module:
CNTL=EXEC,MODULE=modulename
The CNTL=LIST and CNTL=INQ commands cannot be specified in the module.
Construct as many of these modules as you want. Each should have its own entry in the PPT.
CNTL Monitoring Options
The following table describes the CNTL monitoring options and indicates the function to select from the Function Selection Menu to specify the same option.
Option
Description
CNTL Menu Function
ABI
Intercepts all CICS abends.
Not available
ABP
Sets local automatic breakpoint.
Function 22
BYP
Bypasses storage protection, permit SVC, BALR 14,14 and BALR 14,15 instructions.
Function 21
CBP
Sets or removes conditional breakpoints.
Function 12
CCV
Sets or removes code coverage
Not available
CMD
Sets or removes indirect command statements for a program/terminal.
Function 24
CSA
Unprotects area in CSA.
Function 21
CWA
Unprotects area in CWA.
Function 21
DM
Sets or removes data monitoring
Function 16
FEP
Identifies instructions that read certain main storage areas.
Not available
FOL
Continues monitoring after branch to another program.
Function 22
ICT
Instruction counter for preventing AICA abends.
Not available
KEP
Keeps data area in a source listing Keep window.
Not available
LET
Allows modification of storage or load module.
Function 21
LNK
Sets composite support.
Function 23
LMD
Specified the load module name of a composite module.
Not available
MON*
Sets or removes monitoring on locations for segmented monitoring.
Function 14
MUS
Limits number of times a program is monitored.
Function 22
MXR
Limits number of CICS requests.
Function 22
MXS
Limits storage usage.
Function 22
NOM*
Sets or removes monitor off locations for segmented monitoring.
Function 15
NRB
Prevents a read buffer before a breakpoint display.
Not available
NUP
Prevents program from updating files.
Function 22
OVR
Overrides errors that trigger an automatic breakpoint.
Not available
PRO
Protects storage from being modified.
Function 21
RBP
Sets or removes request breakpoints.
Function 13
RFC
Replaces file name.
Function 20
RNT
Prevents program from modifying code.
Function 22
RPC
Replaces program name.
Function 20
RTD
Replaces transient data queue name.
Function 20
RTS
Replaces temporary storage ID.
Function 20
SDF
Structure Display Format Setting
Function 22
SLB
Activates Source Listing Breakpoint display.
Function 22
STR
Saves CICS trace table.
Not available
TAL
Counts how often instruction is executed within loop.
Not available
TER
Changes the terminal ID.
Not available
TFL
Sets a non-interactive monitoring session
Not available
TON
Limits monitoring to single terminal.
Functions 20,21,22
TRC
Sets or removes statement tracing
Function 11
UBP
Sets or removes unconditional breakpoints.
Function 11
USH
Removes storage protection from SHARED storage subpool area.
Not available
USR
Sets monitoring for the CICS user ID specified.
All monitoring and most monitoring options
CNTL Monitoring Option Syntax
To set CNTL options, enter:
CNTL=ON,promid,options or CNTL=ON*,options
To remove CNTL options, enter:
CNTL=OFF,promid,options or CNTL=OFF*,options
To remove an option, specify it exactly as it was originally defined.
To remove an option that was specified more than once for a program, enter:
CNTL=OFF,promid,option=.ALL
The
.ALL specification is valid for the following options: BYP, CBP, CSA, KEP, LET, MON, NOM, PRO, RFC, RPC, RTD, RTS, and UBP.
Examples
To instruct CA InterTest for CICS to limit the number of CICS requests made by program COBDEMO to 40, enter:
CNTL=ON,PROG=cobdemo,MXR=40
To instruct CA InterTest for CICS to stop limiting the number of CICS requests made by program COBDEMO for user ID BARNEY1, enter:
CNTL=OFF,PROG=cobdemo,MXR=40,USR=BARNEY1
To instruct CA InterTest for CICS to remove all RFC options specified for program COBDEMO, enter:
CNTL=OFF,PROG=cobdemo,RFC=.ALL
Multiple Specifications of the Same Option
Multiple specifications of the same option are in effect for a program, transaction, or terminal.
Example
Specify the UBP option at various times to set unconditional breakpoints within a program. Each specification remains in effect until it is removed.
Specify the following options more than once: BYP, CBP, CSA, DM, KEP, LET, MON, NOM, PRO, RFC, RPC, RTD, RTS, SLB, TRC, and UBP. For other options, only one specification is in effect at one time for a program, transaction, or terminal. The last specification is the one that CA InterTest for CICS recognizes.
For the following options, only one specification is in effect at a time: ABI, ABP, FOL, ICT, MUS, MXR, MXS, NUP, RNT, STR, TAL, and TON.
ABI Intercept All CICS Abends
The ABI option intercepts CICS abends and produces automatic breakpoints with an error code and message explaining the reason for the abend. Then select to continue execution (after, possibly, removing the error) or abend the task with the same or different abend code. All abend codes are intercepted, except those generated into the IN25ABEN table by you.
The ABI option has three values: ON, OFF, and FORCE.
  • ABI=ON
    (Default)
    Intercepts all CICS abends and produces automatic breakpoints for programs or tasks that
    do not
    have an active CICS HANDLE ABEND.
  • ABI=FORCE
    Intercepts CICS abends for programs or tasks that have an active CICS HANDLE ABEND command.
  • ABI=OFF
    Causes CA InterTest for CICS to STOP intercepting CICS ABENDS for the specified program.
Examples
CNTL=ON,PROG=ABC,ABI=ON CNTL=ON,PROG=ABC,ABI=OFF CNTL-ON,PROG=ABC,ABI=FORCE
ABP Local Automatic Breakpoint Option
The
local
ABP option activates automatic breakpoints for a specified program, transaction, or terminal.
To set the local automatic breakpoint option, enter:
ABP=termid or ABP=*
  • termid
    Specifies the ID of the terminal to which automatic breakpoint displays should be routed.
  • *
    Specifies that the current terminal should receive automatic breakpoint displays.
    This option overrides the
    global
    automatic breakpoint facility and is useful in a system where the global automatic breakpoint facility is disabled.
The local ABP option is also useful when you do not want the breakpoint display routed to the terminal where the program is running, or when the display cannot be routed to that terminal (for example, a non-terminal task or a task running on a non-3270 terminal). In these cases, specify the
termid
of the terminal to which breakpoint displays should be routed.
Remove the ABP option to deactivate automatic breakpoints for a specified program, transaction, or terminal. If a monitoring violation occurs, CA InterTest for CICS abends the task instead of halting it at an automatic breakpoint.
BYP Bypass Storage Protection
To bypass storage protection and allow SVC and BALR, BASSM, BASR 14,15 and 14,14 instructions, enter:
BYP=(offset1,offset2)
or
BYP=(addr1,addr2)
Specify the beginning and ending program locations either as offsets or addresses.
  • offset
    Specifies a one to five digit hexadecimal displacement from the beginning of the program.
  • addr
    Specifies a six- to eight-digit hexadecimal address.
    This BYP specification defines a section of program code that is allowed to:
    • Modify any area of storage
    • Issue SVC instructions
    • Issue BALR, BASSM, and BASR 14,15 and 14,14 instructions
WARNING!
Use this option with great care! Specify BYP only for a small section of code, such as a CALL statement (that is, a BALR, BASSM, or BASR 14,15 or 14,14 instruction). In that case, monitoring is suspended until control returns to the instruction after the CALL statement. If control does not return, monitoring remains off for the duration of the program's execution.
This BYP specification suspends monitoring when a BALR, BASSM, or BASR 14,15 or 14,14 instruction passes control to the specified location. It is useful when a monitored program calls a non-standard interface from several different locations. Use the following specification to bypass storage protection when a BALR, BASSM, or BASR 14,15 or 14,14 instruction passes control:
BYP=(.ANY,locn)
  • locn
    Specifies a one- to five-digit hexadecimal displacement or a six- to eightdigit hexadecimal address.
Use the following specification to bypass a current instruction at a breakpoint:
BYP=*
This BYP specification instructs CA InterTest for CICS to allow the current instruction to modify storage or issue an SVC, BALR, BASSM, or BASR 14,15 or 14,14 instruction.
Specify this option with great care. It could be password protected.
CBP Specify Conditional Breakpoints
To specify a conditional breakpoint, enter:
CBP=locn,IF=condition
A conditional breakpoint halts a program at a specified location only if a specified condition is met. For more information about specifying the location and the condition, see Conditional Breakpoints.
CCV Code Coverage
This option turns on code coverage for programs, transactions or terminals monitored in a non-interactive session. This option can only be used together with the TFL option.
To turn on coverage, enter
TFL=token,CCV=on
Example
To turn on non-interactive monitoring and get a code coverage data for the program COBDEMO, enter
CNTL=ON,PROG=COBDEMO,TFL=ABCDE,CCV=ON
After the transaction is executed, the monitoring session for the specific program is terminated and an audit log (ABCDE.rpt) and code coverage data (ABCDE.ccv) are generated. The output files are in JSON format.
For more information about the token that is used for the TFL option, see TFL Set Non-Interactive Monitoring.
CMD Set Indirect Command Statements
To set an indirect command statement for a particular program or terminal, enter:
CMD=((number),F=termid),TEXT='command text'
  • number
    Specifies the indirect command statement line number that will be assigned to the accompanying command text.
  • F=termid
    Specifies the terminal where the program for which the indirect commands are being set will execute from. This provides multiple users with the potential for defining independent sets of indirect commands for each of their debugging sessions. In addition, a single set of commands is shared by all users if F=.ANY is specified.
Indirect commands defined under a specific or .NO terminal take precedence over any existing F=.ANY command set.
  • TEXT
    Specifies the actual indirect command text, which must be enclosed within single or double quotation marks. For more information and command syntax, see Indirect Commands.
CSA Unprotect an Area in the CSA
To unprotect an area in the CSA, enter:
CSA=(offset,length)
  • offset
    Specifies a hexadecimal displacement from the beginning of the CSA.
  • length
    Specifies the number of hexadecimal bytes in the CSA to be unprotected.
This option lets a program, transaction, or terminal modify areas in the CSA.
Specify this option with great care. It could be password protected.
CWA Unprotect an Area in the CWA
This option lets a program, transaction, or terminal modify areas in the CWA.
To unprotect an area in the CWA, enter:
CWA=(offset,length)
  • offset
    Specifies a hexadecimal displacement from the beginning of the CWA.
  • length
    Specifies the number of hexadecimal bytes in the CWA to be unprotected.
DM Data Monitoring Option
This option instructs CA InterTest for CICS to capture data values for every COBOL statement executed in the program or transaction, or at a terminal. When data monitoring is set to ON, the statement tracing option (TRC) is forced on for the program, transaction, or terminal.
To set data monitoring for a particular program, transaction, or terminal, enter:
DM=ON
A specific terminal ID or user ID is required to set the data monitoring option. If one is not specified, the default will be used.
FEP Set the FEP Option
The FEP option lets you find program instructions that read from one or more main storage areas specified in the option. The first format of the FEP option identifies main storage areas that a program might read. The second format (FEP=EX,...) prevents the program from reading
all
main storage areas
except
the ones specified in the option and areas owned by the program.
To set the FEP option, enter:
FEP=(addr,len) FEP=(EX,addr,len)
  • addr
    Indicates six to eight digit hexadecimal address of the first byte of a main storage area.
  • len
    Indicates length of the area in hexadecimal.
  • EX
    Prevents the program from reading all main storage areas except those specified in the option or owned by the program.
FOL Continue Monitoring After a Branch to Another Program
This option instructs CA InterTest for CICS to monitor a program even after it branches directly to another program (wild branch). All monitoring options remain in effect.
Specify breakpoints in the load module to which control is passed, but their locations might have to be specified as hexadecimal addresses.
Do not specify this option if control is passed using a LINK or XCTL instruction.
  • Use FOL=ON when control passes to a program that does not have a PPT entry.
  • Use FOL=name when control passes to a program that has a PPT entry.
  • Use FOL=NOPPT instead of ON to reduce overhead.
To continue monitoring after a branch, enter:
FOL=ON
or
FOL=name
or
FOL=NOPPT
ICT Instruction Counter for Preventing AICA Abends
This command instructs CA InterTest for CICS to issue an EXEC CICS WAIT command each time the specified program executes
nnnnn
instructions. Use this option to prevent incorrect AICA abends in high CPU-utilization programs where overhead was increased by the CA InterTest monitoring activity.
To set the instruction counter to prevent an AICA abend, enter:
ICT=nnnnn
  • nnnnn
    Specifies the number of instructions. Replace
    nnnnn
    with a decimal number between 1 and 65,534.
KEP Keep Data Areas in a Keep Window
The KEP= option lets you specify one storage area to be kept in a Keep window whenever the specified program displays or executes from the source listing facility. The Keep window is not available on a Detailed Breakpoint display.
Display up to six items in a Keep window at a time. If you keep more than six items, CA InterTest for CICS initially displays the first six items that you selected but allows scrolling to other items using the PF19 and PF20 keys. When an item is removed from the window, another item is displayed. The KEP= option syntax allows only one request at a time. For each item kept, CA InterTest for CICS displays a single line identifying the keep request, followed by the first 12 bytes of storage in both hexadecimal and character format.
To keep data in a Keep window, enter:
KEP=(request) KEP=((request),T=termid)
  • request
    Specifies one data area in CICS main storage to be displayed in a Keep window. Use CORE syntax to specify the requested data area, but omit CORE=.
  • termid
    Specifies the terminal that displays the requested area in a Keep window.
  • T=.ANY
    Specifies the data area that will display in a Keep window on any terminal that displays or executes the program using LIST.
LET Allow a Program to Modify Storage or a Load Module
To allow a program to modify storage, enter:
LET=(address,length)
  • address
    Specifies the starting address of the area of storage that is modified as six to eight hexadecimal digits.
  • length
    Specifies, in hexadecimal, the number of bytes that are modified.
The storage area must lie entirely within the CICS Dynamic Storage Area.
To allow a program to modify a load module, enter:
LET=progname
  • progname
    Specifies the load module that is modified.
Specify this option with great care. It could be password protected.
LNK Set Composite Support
Use LNK options to set composite support for a
composite module
. A composite module consists of separately compiled or assembled parts brought together when the module is link-edited.
The part of the composite module that receives control from CICS is referred to as the
main
program; the remaining parts are referred to as
subprograms
. These programs are written in the same or different languages.
Composite support lets you test and debug a subprogram as if it were a separate program. Specify a separate LNK option for the main program and for each subprogram you want to test separately.
It is easier to set LNK options on the CNTL Composite Support screen than with single-line commands. Most of the necessary information is supplied in a CA InterTest for CICS batch job step.
To set composite support for a composite module, enter:
LNK=(composite module information)
LMD Specify Load Module
Use the LMD option to specify a particular
composite load module name
when setting or changing the monitoring options for its subprograms. For more information about the composite support, see Monitoring Menu Options.
This option applies for
Composite Support
only. It is reasonable to use this option only if a subprogram exists in multiple composite modules.
To specify a load module, enter:
LMD=lmdname
  • lmdname
    Specifies the load module name of a composite module.
Example:
Assume two composite modules COBDEML1 and COBDEML2 are being monitored. Both of the composite modules contain a subprogram called ASBIN25.
An unconditional breakpoint at statement number 00098 of the subprogram ASBIN25 residing in the composite module COBDEML2 is requested. Following CNTL command can be used:
CNTL=ON,PROG=ASBIN25,UBP=00098,LMD=COBDEML2
MON Set Monitor ON Locations for Segmented Monitoring
The segmented monitoring options MON and NOM may cause unpredictable damage to the CICS system if not used properly. For more information about using MON and NOM, see Special Monitoring Situations. MON and NOM pertain to all users and are not user ID sensitive.
Notes:
MON is supported only in releases 5.1 and higher. MON options are not user ID sensitive and pertain to all users.
To set monitor on locations for segmented monitoring, enter:
MON=locn MON=(locn1,locn2,...,locn9)
  • locn
    Specifies a
    program
    location where CA InterTest for CICS starts or continues monitoring using the special segmented monitoring method. The location must specify the op-code of a machine instruction that resides in non-store-protected virtual storage.
Specify, in quotes, the location as a COBOL paragraph name or a PL/I or Assembler label; without quotes a COBOL or PL/I statement number (a decimal number preceded by a # sign), or a hexadecimal displacement from the beginning of the program, or an address in main storage.
MUS Limit the Number of Times a Program Is Monitored
To limit the number of times a program is monitored, enter:
MUS=limit
  • limit
    Specifies the number of times a program is monitored. Replace
    limit
    with a decimal number from 1 to 65,534.
MXR Limit the Number of CICS Requests
The MXR option is useful when a program is in a loop that includes a CICS request and therefore will not time out.
To limit the number of CICS request, enter:
MXR=nnnnnnn
  • nnnnnnn
    Specifies the number of CICS requests a program issues. Replace
    nnnnnnn
    with a decimal number up to one million.
MXS Limit Storage Usage
To limit storage usage, enter:
MXS=nnnnnnn
  • nnnnnnn
    Specifies the amount of storage, including program storage that a program acquires. Replace
    nnnnnnn
    with a decimal number up to one million.
NOM Set NO Monitor Locations for Segmented Monitoring
The segmented monitoring options MON and NOM might cause unpredictable damage to the CICS system if not used properly. For more information about using MON and NOM, see Special Monitoring Situations. MON and NOM pertain to all users and are not user ID -sensitive.
Notes:
NOM is supported in releases 5.1 and higher, only. NOM is not user ID sensitive and pertains to all users
To set no monitor locations for segmented monitoring, enter:
NOM=locn NOM=(locn1,locn2,...,locn9)
  • locn
    Specifies a
    program
    location where CA InterTest for CICS stops monitoring using the special segmented monitoring method. The location must specify the op-code of a machine instruction that resides in non-store-protected virtual storage.
Specify the location as a COBOL paragraph name (in quotes), a PL/I or Assembler label (in quotes), a COBOL or PL/I statement number (a decimal number preceded by a # sign), or a hexadecimal displacement from the beginning of the program. The location also specifies an address in main storage.
NRB Prevent a Read Buffer Before a Breakpoint Display
The read buffer request lets CA InterTest for CICS restore the screen when you are finished with the breakpoint display. However, if the read buffer cannot be executed because the terminal or transmission network prevents it, you must issue the NRB option to prevent the request.
To prevent CA InterTest from issuing a read buffer before displaying a breakpoint, enter:
NRB=ON
NUP Prevent a Program from Updating CICS Files
The NUP option prevents a program from actually updating VSAM and BDAM CICS files. This option allows repeated tests of transactions without altering test records. The NUP option also prevents test programs from modifying production files.
To prevent a program from updating CICS files, enter:
NUP=ON
OVR Override Error Conditions That Trigger an ABP
The OVR option instructs CA InterTest for CICS to ignore error conditions that would otherwise trigger an automatic breakpoint. For a list of error codes, see Examining Dumps.
To override an error that could trigger an ABP, enter:
OVR=errcode
or
OVR=(errcode1,errcode2,...)
  • errcode
    Specifies a hexadecimal CA InterTest for CICS error code.
Use caution in specifying this option. Remember, it forces CA InterTest for CICS to ignore potentially dangerous conditions.
PRO Protect Storage from Being Modified
The PRO option generates an automatic breakpoint whenever the monitored program attempts to modify the protected area. This is useful when you are trying to determine how an area of storage is being modified.
Specify the PRO option while a program is at a breakpoint if the storage location is different each time the program executes.
To protect storage from being modified, enter:
PRO=(address,length)
  • address
    Specifies the starting address of the protected storage area as six- to eight-hexadecimal digits.
  • length
    Specifies, in hexadecimal, the number of protected bytes.
RBP Specify Request Breakpoints
The RBP option lets you halt a program prior to all CICS commands, DL/I, DB2, or calls to software recognized by CA InterTest for CICS. This option also lets you halt a program prior to specific CICS commands, such as File Control or Program Control commands. Most users will find it easier to use the CNTL Command Builder menus rather than the RBP option to specify request breakpoints.
If the F=term1 or T=term2 parameter is omitted, it defaults to the terminal that issued the RBP option.
To specify request breakpoints, use the following commands:
RBP=request RBP=(request1,request2,...,request9) RBP=((request),F=term1,T=term2) RBP=((request1,...,request9),F=term1,T=term2) RBP=((request),F=term1,T=term2,L=loopnumber) RBP=((request1,...,request9),F=term1,T=term2,L=loopnumber)
  • request
    Specifies where the request breakpoint should occur:
    • ALLCOM prior to all CICS commands
    • ALLDLI prior to all DL/I calls
    • ALLCAL prior to all calls to software CA InterTest for CICS has been instructed to recognize at installation time
    • code
      prior to the CICS commands represented by the code
    For a list of valid codes, see the Help facility.
  • term1
    Specifies the terminal at which the program must be executing for the breakpoint to take effect. F=.ANY specifies that the breakpoint take effect at all terminals -- even when the program executes without a terminal. F=.NO specifies that the breakpoint take effect only when the program executes without a terminal.
  • term2
    Specifies the terminal to which the breakpoint display is sent. T=.ANY specifies that the breakpoint display be sent to the terminal at which the program is executing.
  • loopnumber
    Specifies how often the program should be halted at the breakpoint.
Example
L=2 halts the program every other time it reaches the specified command; L=13 halts it every thirteenth time. If this parameter is omitted, the breakpoint occurs every time the program reaches the specified command. This parameter is especially useful when a CICS command occurs within a loop; for example, during a browse.
RFC Replace File Names
The RFC option dynamically substitutes one file name for another during program execution. This is useful when you want to use test files in a production environment, or when you want to use several different files to test a program.
To replace file names, enter:
RFC=(file1,file2)
  • file1
    Specifies the file to be replaced.
  • file2
    Specifies the file that will replace
    file1
    .
RNT Prevent a Program from Modifying Its Own Code
The RNT option lets you test a program for reentrancy by preventing the program from modifying its own code.
To prevent a program from modifying its own code, enter:
RNT=ON
RPC Replace Program Names
The RPC option dynamically substitutes one program name for another in LOAD, LINK, and XCTL requests made by a monitored program. This lets multiple copies of a program coexist in one system, provided each has its own PPT entry. Use the RPC option when you want to test a program using modules other than the ones coded in the program.
To replace program names, enter:
RPC=(prog1,prog2)
  • prog1
    Specifies the program to be replaced.
  • prog2
    Specifies the program to replace
    prog1
    .
RTD Replace Transient Data Queue Names
The RTD option dynamically substitutes one transient data queue name for another during program execution so you can test a program using transient data queues other than the ones coded in your program.
To replace transient data queue names, enter:
RTD=(name1,name2)
  • name1
    Specifies the transient data queue name to be replaced.
  • name2
    Specifies the transient data queue name to replace
    name1
    .
RTS Replace Temporary Storage Identifications
The RTS option dynamically substitutes one temporary storage identification for another during program execution so you can test a program using temporary storage identifications other than the ones coded in your program.
To replace temporary storage IDs, enter:
RTS=(mask1,mask2)
  • mask1
    Specifies the temporary storage ID to be replaced.
  • mask2
    Specifies the temporary storage ID to replace
    mask1
    .
Specify both masks as eight bytes in either character (C' data' ) or hexadecimal (X' data') format.
SDF Structure Display Format Setting
To override, by program, the global default setting, enter:
SDF=HEX or SDF=DATA
  • HEX
    Displays data in hexadecimal or character format.
  • DATA
    Displays data in Structure Display Format.
SLB Activate the Source Listing Breakpoint Facility
This option activates the Source Listing Breakpoint display for the specified terminal.
To activate the source listing breakpoint facility, enter:
SLB=termid SLB=*
  • termid
    Specifies the terminal to receive breakpoint displays.
  • *
    Specifies the terminal from which the option is issued.
STR Save the CICS Trace Table
The STR option instructs CA InterTest for CICS to preserve a copy of the CICS trace table when a program stops at a breakpoint. Issue the command CORE=STRA to display the table. The most recent table entries display first; view earlier entries by scrolling through the display.
To save the CICS trace table, enter:
STR=ON
TAL Count How Often an Instruction Is Executed
The TAL option counts the number of times a program reaches a specified location. This option is useful with a conditional breakpoint because it lets you specify how often a program should be halted within a loop. Use the
loopnumber
parameter when specifying an unconditional breakpoint to perform the same task.
To count the number of times an instruction executes, enter:
TAL=locn
  • locn
    Specifies a
    program
    location as a COBOL paragraph name (in quotes), a PL/I or Assembler label (in quotes), a COBOL or PL/I statement number (preceded by a # sign), or a hexadecimal displacement from the beginning of the program.
TER Change the Terminal ID
The TER option changes all occurrences of the old terminal ID to the new terminal ID whenever a terminal ID is specified for an online option; for example, in a UBP option. This is useful when you have set terminal-specific options, and then need to move to another terminal to continue testing.
To change the terminal ID, enter:
TER=(oldtrm,newtrm)
  • oldtrm
    Specifies the old terminal ID.
  • newtrm
    Specifies the new terminal ID.
TFL Set Non-Interactive Monitoring
This option instructs CA InterTest for CICS to set a non-interactive monitoring session. This option disables automatic breakpoints in monitored programs, transactions or terminals, and disables all breakpoint options. The non-interactive monitoring session is set for a one-time occurrence only. Once the session is run, the monitoring is automatically disabled.
Non-Interactive monitoring is intended for collecting code coverage and/or trace data. This monitoring should be used for transactions that complete successfully as not all the diagnostic data are available for failing transactions during non-interactive processing.
This option accepts a token with a maximum of 8 characters as an input. The token must be unique for each monitoring session, and is used to generate the report outputs of the non-interactive session. These outputs include an audit log detailing the execution of the program, code coverage, and trace data. Use the CCV and TRC options to enable code coverage and trace data creation.
The USSPATH specified under installation options for CA InterTest for CICS is used as a directory to save these files. If the USSPATH is not specified correctly, this option is disregarded and error message CAIN4624 displays. For more information on USSPATH, see IN25OPTS Keywords.
To turn on non-interactive monitoring and produce an audit log, enter
TFL=token
The audit log file generated from a non-interactive session will be in JSON format. This file contains a general report on monitoring entries, time stamp, reason for termination of program execution and final values of general purpose registers.
Example
To turn on non-interactive monitoring for program COBDEMO, enter
CNTL=ON,PROG=COBDEMO,TFL=ABCDE
After the transaction executes, the monitoring session for the specific program is terminated and an audit log (ABCDE.rpt) is generated.
Non-interactive monitoring has precedence over normal (interactive) monitoring sessions.
TON Limit Monitoring to One Terminal
The TON option instructs CA InterTest for CICS to monitor a program or transaction only when it executes at a specific terminal or without a terminal.
To limit monitoring to a single terminal, enter:
TON=termid
or
TON=*
or
TON=.NO
  • termid
    Specifies the terminal the program must execute from to be monitored.
  • *
    Specifies that the program must execute at the current terminal to be monitored.
  • .NO
    Specifies that the program must execute without a terminal to be monitored.
TRC Statement Tracing Option
This option instructs CA InterTest for CICS to save trace information for every COBOL statement executed in the program or transaction, or at a terminal.
To set statement tracing for a particular program, transaction, or terminal, enter:
TRC=ON
This option is unrelated to the backtrace facility.
If this option is used together with the TFL option, a statement trace report is generated upon program execution.
TFL=Token,TRC=ON
The file generated is in JSON format and includes the execution flow of the monitored program.
Examples
To turn on non-interactive monitoring and get statement trace data for the program COBDEMO, enter
CNTL=ON,PROG=COBDEMO,TFL=ABCDE,TRC=ON
After the transaction executes, the monitoring session for the specific program is terminated and an audit log (ABCDE.rpt) and trace data (ABCDE.trc) are generated.
For more information about the token that is used for the TFL option, see TFL Set Non-Interactive Monitoring.
UBP Specify Unconditional Breakpoints
To specify unconditional breakpoints, use the following commands:
UBP=locn UBP=(locn1,locn2,...,locn9) UBP=((locn),F=term1,T=term2) UBP=((locn1,...,locn9),F=term1,T=term2) UBP=((locn),F=term1,T=term2,L=loopnumber) UBP=((locn1,...,locn9),F=term1,T=term2,L=loopnumber) ubp=((ALLPAR),F=term1,T=term2,L=loopnumber) ubp=((ALLLAB),F=term1,T=term2,L=loopnumber)
  • locn
    Specifies a program location as a COBOL paragraph name (in quotes), a PL/I or Assembler label (in quotes), a COBOL or PL/I statement number (preceded by a # sign), or a hexadecimal displacement from the beginning of the program. locn also specifies an address in main storage.
The following operands specify the terminal at which the program must be executing for the breakpoint to take effect.
  • F=.ANY
    Specifies that the breakpoint take effect at all terminals, even when the program executes without a terminal.
  • F=.NO
    Specifies that the breakpoint take effect only when the program executes without a terminal.
  • term2
    Specifies the terminal to which the breakpoint display is sent.
  • T=.ANY
    Specifies that the breakpoint display be sent to the terminal at which the program is executing.
If the F=term1 or T=term2 parameter is omitted, it defaults to the terminal that issued the UBP option.
  • loopnumber
    Specifies how often the program should halt when a breakpoint is within a loop.
Example
L=2 halts the program every other time it passes through the loop; L=3 halts it every third time. If this parameter is omitted, the breakpoint occurs every time the program reaches the location.
  • ALLPAR
    Specifies that breakpoints take effect at
    all
    COBOL paragraph names.
  • ALLLAB
    Specifies that breakpoints take effect at
    all
    Assembler labels.
When you set unconditional breakpoints, CA InterTest for CICS halts the program at the specified locations.
USH Unprotect Shared Storage
The USH option removes storage protection from all main storage areas residing in the SHARED storage subpool. This option lets a program change all CLASS=SHARED storage, and other storage areas in the SHARED subpool. FREEMAINs of these areas are permitted; however, the four-byte Storage Accounting Areas remain protected.
To unprotect shared storage, enter:
USH=ON
The TER option changes all occurrences of the old terminal ID to the new terminal ID whenever a terminal ID is specified for an online option; for example, in a UBP option. This is useful when you have set terminal-specific options, and then need to move to another terminal to continue testing.
Use this option with extreme caution.
USR Limit Monitoring to a CICS User ID
When security is active in the region and the IN25OPTS global installation option is set to DFLTUSR=SPECIFIC, a signed on user's monitoring request defaults to using the requester's individual user ID (USR=userid). Otherwise, the default USR= option is set to .ANY.
Monitoring options set for a specific user ID have advantages. The From and To terminals automatically default to .ANY. This means that you can switch terminals and continue to have monitoring, breakpoints, and options set for his user ID directed to the new terminal.
For releases 5.4 and higher, to limit monitoring to a specific CICS user ID in a secure region, enter:
USR=userid
  • userid
    Specifies CICS user ID.
To monitor all users of the
promid
, enter:
USR=.ANY