Add Breakpoint (ADDBKP)

The Add Breakpoint (ADDBKP) command sets up to ten 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 any 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. To specify different sets of variables for each breakpoint, you must use separate commands.

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) shows the values of the specified program variables when the program is stopped. This information is also written to the job log. From the display, the user can press the F10 key to show the command entry display, or press the F3 key to exit the display and cancel the program. The user can press 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 can be called to take action on the breakpoint condition. The name of the called program is specified on the Breakpoint program to call (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 displayed. You must press the Enter key, allowing the stopped program to continue, before returning to the previous display.

Restrictions:

• You can use this command only in debug mode. To start debug mode, refer to the Start Debug (STRDBG) command.
• You cannot use this command if you are servicing another job, and that job is on a job queue, or is being held, suspended, or ended.

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

• To use this command, you must have all object (*ALLOBJ) special authority.

Parameters

Statement identifier (STMT)

Specifies the statement identifiers of one to ten statements or machine instructions in the program at which breakpoints are set. When run, the program breaks before processing a statement specified as a breakpoint.

This is a required parameter.

The list can contain a maximum of 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.

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

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 added breakpoint.

Program variables (PGMVAR)

Specifies the names of up to ten program variables shown that are in a high-level language or machine instruction program. The name and the value of each program variable is shown when any of the breakpoints specified on the Statement identifier (STMT) parameter are reached. When 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.

Single values

*NONE

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

Other values (up to 10 repetitions)

Element 1: Program variable

*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.

character-value

Specify the names of one to ten program variables, separated by blanks, shown when a breakpoint is reached. The name must be enclosed in apostrophes if it contains special characters.

If the program variable is an array, the subscripts representing the element in the array can be specified. 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 may 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 topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Element 2: Basing pointer variable

character-value

Specify up to five basing pointers for each program variable to be shown. In some languages, the program variable may be based on a pointer variable. This set of values allows you to explicitly specify the basing pointers for the variable being recorded. 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, a machine-interface object-definition-table-vector (MI ODV) number, or a numeric variable name can be specified for a subscript.

For more information, refer to "Parameter values used for testing and debugging" in "CL concepts and reference" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Output format (OUTFMT)

Specifies the format used to show the variables.

*CHAR

Variables are shown in character form.

*HEX

Variables are shown in hexadecimal form.

Program (PGM)

Specifies 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.

name

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

Char output start position (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 for the Program variables (PGMVAR) parameter, the same starting position value is used for each one. For a bit string, the value specifies the starting bit position, and for a character string, the value specifies the starting character position.

For conditional breakpoints, the Char output start position (START) parameter also specifies the starting point in the string where the comparison is made.

1

The variable is shown from the first position onward through the length specified by the value supplied for the Characters to display (LEN) parameter.

integer

Specify the first position of the program variable to be shown.

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

Characters to display (LEN)

Specifies, for string variables only, the length of the string shown when the breakpoint is reached, starting at the position specified by the value supplied for the Char output start position (START) parameter. If more than one string variable is specified by the value supplied for the Program variables (PGMVAR) parameter, the same value is used for each one. For a bit string, the value specifies the number of bits shown, and for a character string, the value specifies the number of characters shown.

For conditional breakpoints, the Characters to display (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 zero, the only allowable value for the LEN parameter is *DCL.

integer

Specify the length of the data shown. The length, as well as the combination of values supplied for the START parameter and the LEN parameter must be no greater than the length of the shortest string specified by the value supplied for the PGMVAR parameter.

Skip value (SKIP)

Specifies the number of times the statement or statements on the Statement identifier (STMT) parameter must be processed before the program is stopped.

0

The program stops immediately when the statement or statements are processed. No skipping of breakpoints is done.

integer

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

Breakpoint condition (BKPCOND)

Specifies a condition, defined by an expression, that must be true before the program is stopped. The expression is tested before any statement on the Statement identifier (STMT) parameter is processed. If the expression is false, the breakpoint does not stop the program. If the expression is true, the program is stopped.

*NONE

No breakpoint expression is specified.

breakpoint-expression

Specify a breakpoint expression indicating a conditional breakpoint. A breakpoint expression consists of these three parts:

• A variable (*PGMVAR1 to *PGMVAR10)
• An operator
• A compare value

variable

Specify the variable to be used in the breakpoint expression. For example, *PGMVAR1 indicates the first variable of the Program variables (PGMVAR) parameter, *PGMVAR2 indicates the second, and so on. Only numeric, character, or bit variables may be specified.

operator

Specify what type of comparison is 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

Note: The *CT operator compares 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.

compare-value

Specify a constant or another variable to compare with the first 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 first 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 may not 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 and 20 digits to the right. To compare them requires a variable with 22 digits to the left of the decimal and 20 to the right. This exceeds the maximum number of allowed digits, 31.

When comparing two character strings, the shorter of the two will be padded on the right with blanks. When comparing two bit strings, they must both be of the same length. The Skip value (SKIP) parameter and the Breakpoint condition (BKPCOND) parameter may be used together. In this case, the breakpoint expression is not evaluated until the breakpoint has skipped the number of times specified by SKIP. After that, the breakpoint expression is evaluated and the program stops if the expression is true.

Breakpoint program to call (BKPPGM)

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

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-digit 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, starting with the statement that has the breakpoint on it.

Single values

*NONE

No breakpoint-handling program is called when any breakpoint specified in this command is reached in the batch environment. The stopped program continues processing.

Qualifier 1: Breakpoint program to call

name

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

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is used to locate the program. If no library is specified as the current library for the job, QGPL is used.

name

Specify the library where the program is located.

Examples

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

*ESCAPE Messages

CPF1999

Errors occurred on command.