ADDBKP (Add Breakpoint)

ADDBKP Command syntax diagram

 

Purpose

The Add Breakpoint (ADDBKP) command sets up to 10 breakpoints in a program.

A breakpoint is a location in a program where processing stops and control is given to the user or to a specified program. The breakpoint is set when a statement number or label of a command or machine instruction is specified. The program is stopped just before processing begins on the statement (or machine instruction) on which the breakpoint is set.

This command shows the values of certain program variables when a breakpoint in the program is reached. As many as 10 variables per breakpoint can be specified, and as many as 10 breakpoints per command can be set. However, the same program variables apply to every breakpoint specified in the command. Different ADDBKP commands must be used to specify different sets of variables for each breakpoint.

This command specifies conditional breakpoints in which the program is stopped when a condition is true. This condition involves two program variables or one program variable and a constant. When using conditional breakpoints, it is possible to stop the program when a program variable becomes a certain value.

A conditional breakpoint can also be specified by specifying a skip value. The program does not stop until the breakpoint statements have been processed as many times as the skip number indicates. After that, the breakpoint causes the program to stop.

When a breakpoint is reached in the interactive debugging environment, a display is shown to the user that identifies which breakpoint has been reached and (optionally) the values of the specified program variables when the program is stopped. A message is also written to the job log when the breakpoint is reached. From the display, the user presses F10 to show the command entry display, presses F3 to exit the display and cancel the program, or presses the Enter key to allow the program to continue running.

When a breakpoint is reached in the batch debugging environment, the breakpoint information is written to a printer file and, optionally, another program is called to take action on the breakpoint condition. The name of the called program is specified in the BKPPGM parameter.

When an interactive job is debugging another job, and a breakpoint is reached in the debugged job, a breakpoint display is shown. This display appears in the debugging job, interrupting what was previously being shown. The user must press the Enter key, allowing the stopped program to continue, before returning to the previous display.

 

Restrictions

  1. This command is valid only in the debug mode. For more information on how to start the debug mode, refer to the description of the STRDBG (Start Debug) command.

  2. This command cannot be used if the user is servicing another job, and that job is on a job queue, or is being held, suspended, or ended.

  3. This command cannot be used to add breakpoints to a bound program.

 

Required Parameters

STMT
Specifies the statement identifiers of up to 10 statements or machine instructions in the program at which breakpoints are set. The program stops before processing a statement specified as a breakpoint.

The list can contain up to 10 identifiers (statement numbers, program labels, or machine instruction numbers) that are valid for the program specified by the PGM parameter. At least one identifier is needed. If a machine instruction number is specified, a slash must be placed in front of the number and both the slash and the number must be enclosed in apostrophes; for example, STMT('/21').

In high-level language programs, different statements and/or labels can be mapped to the same internal instruction. This happens when several statements that do not operate on variables directly (such as DO, END, and comments) follow one another in a program. The intermediate representation of a program list is used to determine which statements can be mapped to the same instruction.

Because different statements can be mapped to the same instruction, adding a breakpoint can redefine a previous breakpoint that was added for a different statement. When this occurs, the new breakpoint replaces the previously defined breakpoint.

 

Optional Parameters

PGMVAR
Specifies the names of up to 10 program variables shown that are in a high-level language or a machine instruction program. The name and value of each program variable is shown when any of the breakpoints specified in the STMT parameter are reached. During a run, the program stops before processing a statement specified as a breakpoint.

Note: In some high-level languages such as RPG, variables that are declared but not referred to in the program cannot be specified on the PGMVAR parameter.

*NONE: No program variables are shown for any of the breakpoints specified.

Element 1: Program Variables

*CHAR: This special value is specified instead of a variable name if a basing pointer is also specified. This special value displays a character view of a pointer to be shown without the use of a based variable.

'program-variable': Specify the names of up to 10 program variables, separated by blanks, shown when a breakpoint is reached. The names must be enclosed in apostrophes if they contain special characters. For example, a CL variable, &VAR, must be specified as PGMVAR('&VAR').

If the program variable is an array, the subscripts representing an element in the array can be specified as a breakpoint. If an array name is specified without any subscripts, all of the array elements are recorded. A single-dimensional cross-section can also be specified. Up to 132 characters can be specified for this program variable entry. This includes any qualifiers, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used.

An integer, a machine-interface object-definition-table-vector (MI ODV) number, asterisk (single-dimensional cross-section), or a numeric variable name can be specified for a subscript. For more information on testing and debugging at machine interface level and on the program-variable value, refer to the CL Programming 

PGMVAR(A)
PGMVAR('A(2,B)')
PGMVAR('B(I1,*,I3)')
PGMVAR('VAR1 OF A(I,J IN B)')

Element 2: Basing Pointers

'basing-pointer': Specify up to five basing pointers for the program variable being shown. In some languages, the program variable can be based on a pointer variable. Each basing pointer name must be enclosed in apostrophes if it contains special characters.

If the basing-pointer is an array, the subscripts representing an element in the array must be specified. Up to 132 characters can be specified for a basing-pointer name. This includes any qualification, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, an MI ODV number, or a numeric variable name can be specified for a subscript. For more information on the basing-pointer value, refer to parameter values used for testing and debugging. Some examples are: 

PGMVAR(('VAR1(B,5)' 'PTR2(C,P2)'))
PGMVAR((VAR2 (BASEPTRA BASEPTRB)))
START
Specifies, for string variables only, the starting position in the string from which its value is shown when the breakpoint is reached. If more than one string variable is specified in the PGMVAR parameter, the same starting position value is used for each one. For a bit string, the value specifies the starting bit position; for a character string, the value specifies the starting character position.

For conditional breakpoints, the START parameter also specifies the start in the string where the comparison is made.

1: The scope of the open data path (ODP) is the job in which the program occurs. If the job is multi-threaded, only those opens from the same thread can share this ODP.

starting-position: Specify the first position of the program variable being shown.

The START value specified must not be larger than the maximum string length for any variable specified, except that START(1) is allowed if the maximum length for a string is 0. The LEN value, plus the START position minus one, must not be greater than the maximum string length. These checks are made for each string variable specified in the PGMVAR parameter.

LEN
Specifies, for string variables only, the length of the string shown when the breakpoint is reached, starting at the position specified by the START parameter. If more than one string variable is specified in the PGMVAR parameter, the same value is used for each one. For a bit string, the value specifies the number of bits shown; for a character string, the value specifies the number of characters shown.

For conditional breakpoints, the LEN parameter also specifies the length of the string where the comparison is made.

*DCL: The string variable is shown to the end of the string or for a value of 200 bytes, whichever is less. If the string variable has a maximum length of 0, only LEN(*DCL) is allowed.

displayed-length: Specify the length of the data shown. The length (as well as the combination of START and LEN) must be no greater than the length of the shortest string specified in the PGMVAR parameter.

OUTFMT
Specifies the format in which the objects are shown.

*CHAR: Variables are shown in character form.

*HEX: Variables are shown in both character format and hexadecimal format.

SKIP
Specifies the number of times the statement or statements on the STMT parameter must be processed before the program is stopped.

0: The program stops immediately when the statement or statements on the STMT parameter are processed. No skipping of breakpoints is done.

skip-value: Specify the number of times the statements on the STMT parameter must be processed before the program is stopped. If there is more than one statement specified, each statement will have its own independent skip value. There is a separate skip count for each statement.

BKPCOND
Specifies a defined condition that must be true before the program is stopped. The condition is tested before any statement on the STMT parameter is processed. If the condition is false, the breakpoint does not stop the program. If the condition is true, the program is stopped.

*NONE: No breakpoint condition is specified.

Element 1: Variable

variable: Specify a variable to be used in the breakpoint condition. *PGMVAR1 indicates the first variable, *PGMVAR2 the second, and so on. Only numeric, character, or bit variables can be specified.

Element 2: Operator

operator: Specify the type of comparison to be done for a conditional breakpoint. The following comparisons are allowed: 

  *EQ - equal to
  *NE - not equal to
  *GT - greater than
  *LT - less than
  *GE - greater than or equal to
  *NL - not less than (same as *GE)
  *LE - less than or equal to
  *NG - not greater than (same as *LE)
  *CT - contains

The *CT operator compares character strings to determine whether one character string contains one or more occurrences of another character string. This comparison is for an exact match, and it is case sensitive.

Element 3: Comparing a Constant or Variable

compare-value: Specify a constant or another variable to compare with the variable. If a constant is specified, it must be the same type as the variable. If the variable is numeric, the constant must be a number. If the variable is a bit, the constant must be a string containing only 1's and 0's. If the variable is a character, the compare value is treated as a character string, even if a number is specified.

If another program variable is specified, it is compared with the variable. The variables must be of the same type. If the variables are numeric, they must both be floating point or not floating point. For example, a packed number cannot be compared with a floating point number.

When comparing two non-floating point variables, or a non-floating point variable and a constant, the total number of digits needed to represent them must not exceed 31. For example, a PACKED(24,2) and a PACKED(24,20) cannot be compared. The first variable requires 22 digits to the left of the decimal point and two digits to the right. The second variable requires four digits to the left of the decimal point and 20 digits to the right. To compare these variables would require a variable with 22 digits to the left of the decimal point and 20 digits to the right. This exceeds the maximum number of allowed digits, 31.

When comparing two character strings, the shorter of the two is padded with blanks. When comparing two bit strings, they must both be of the same length.

The SKIP and BKPCOND parameters can be used together. In this case, the breakpoint condition is not evaluated until the breakpoint has skipped the number of times specified by SKIP. After that, the breakpoint condition is evaluated and the program stops if the condition is true.

BKPPGM
Specifies the qualified name of the user-supplied program (if any) to call when a breakpoint is reached in the program specified by the PGM parameter. When the program specified on the BKPPGM parameter is called, it is passed four parameters that identify: the program name, the recursion level, the high-level language statement identifier, and the machine instruction number at which the breakpoint occurred. Those four parameters have the following formats:

  1. Program name (10 bytes). The name of the program in which the breakpoint was reached.

  2. Recursion level (5 bytes). The recursion level number of the program in which the breakpoint was reached. This value is a 1- to 5-digit number that is padded on the right with blanks.

  3. Statement identifier (10 bytes). The high-level language program statement identifier that was reached. This statement identifier is the statement identifier specified in the Add Breakpoint (ADDBKP) command that defined the breakpoint. If a machine instruction number was used to specify the breakpoint, this parameter contains a slash (/) followed by a 4-digit hexadecimal machine instruction number.

  4. Instruction number (5 bytes). The machine instruction number that corresponds to the high-level language statement at which the breakpoint was reached. No slash appears in front of this machine instruction number. It consists of 1 to 4 hexadecimal characters that represent the MI instruction number, followed by one or more blanks. If a machine instruction number is passed in the third parameter, the numbers in the third and fourth parameters are the same.

All the parameter values are left-adjusted and padded with blanks. When the called program returns, the program being debugged continues processing, with the statement with the breakpoint on it.

*NONE: No breakpoint-handling program is called when any breakpoint specified in this ADDBKP command is reached in the batch environment. The interrupted program continues processing.

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the user-supplied program to call if any of the breakpoints on this command are reached while debugging in a batch environment. The program specified should not be the same as the program specified in the PGM parameter. If they are the same, the results are unpredictable. After the called program runs, it returns control to the interrupted program, which continues processing.

PGM
Specifies the name of the program to which the breakpoints are added.

*DFTPGM: The breakpoints are added to the program currently specified as the default program in debug mode.

program-name: Specify the name of the program to which the breakpoints are added. The program must already be in debug mode.

Examples for ADDBKP

Example 1: Adding Breakpoints in Debug Mode 

ADDBKP  STMT(150 RTN1 205)
  PGMVAR('&TEMP' '&INREC')

This command establishes breakpoints at CL statement numbers 150 and 205 and at the label RTN1 for the default program in debug mode. When any of these breakpoints is reached, the CL variables &TEMP and &INREC are automatically shown. Note that the CL variables must include a leading ampersand (&) and be specified within apostrophes.

Example 2: Adding Breakpoints to HLL Program 

ADDBKP  STMT(100)  PGMVAR('AMOUNT(200)')
  PGM(MYPROG)

Assume in this example that MYPROG is a high-level language program being debugged in an interactive environment and that the program variable AMOUNT is a 250-element array in MYPROG. This command adds a breakpoint to statement 100 in MYPROG. When MYPROG is started, the program stops processing at statement 100, and the value of the 200th element of the AMOUNT array is shown. If AMOUNT had been specified without a subscript, all of the array elements would have been shown.

Example 3: Program Stops After Processing Statement 10 Times 

ADDBKP   STMT(10)  SKIP(1000)

This command causes the default program to stop when statement 10 is processed 1000 times (the breakpoint is skipped 1000 times).

Example 4: Program Stops After Processing Multiple Statements 

ADDBKP   STMT(10 20 30)  SKIP(50)

This command causes the default program to stop when statements 10, 20, and 30 are processed 50 times.

Example 5: Conditional Breakpoint 

ADDBKP   STMT(10)  PGMVAR(X)  BKPCOND(PGMVAR1 *EQ 5)

This command stops the default program at statement 10 when variable X is equal to five.

Example 6: Conditional Breakpoint 

ADDBKP   STMT(20)  PGMVAR((S1) (S2))  SKIP(100)
  BKPCOND(*PGMVAR1 *CT *PGMVAR2)

This command stops after statement 20 has been processed 100 times, and then only if the character string S2 occurs in the character string S1.

Error messages for ADDBKP

*ESCAPE Messages

CPF1999
Errors occurred on command.