Add Trace (ADDTRC)

The Add Trace (ADDTRC) command specifies which program statements in a program to trace in debug mode. Up to five ranges of high-level language (HLL) statements or machine instructions can be traced during the processing of a program through one or more ADDTRC commands, and up to 10 program variables can be recorded or monitored for change in each specified statement range. A separate ADDTRC command is required for each unique variable associated with a statement range. When the specified program being traced is run, the system records the sequence in which the traced statements are processed and optionally records the value of the variables associated with the trace each time a traced statement is processed. After a trace has been completed, you can display this information using the Display Trace Data (DSPTRCDTA) command.

All of the trace ranges specified in a program are active at the same time. If both an HLL statement identifier and a machine instruction number are used to specify a given trace range, the trace range is treated as an HLL trace range. That is, in addition to tracing the machine instruction number specified, the system traces the HLL statement identifiers between that machine instruction number and the specified HLL statement identifier. More information on testing and debugging at the machine interface level is in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

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.

• You cannot use this command to trace bound programs.

Parameters

Statements to trace (STMT)

Specifies which program statements (or machine instructions) to trace in the program.

*ALL

All statements in the specified high-level language program are traced.

*ALLINST

All machine instructions in the specified program are traced.

start-statement-identifier stop-statement-identifier

Specify the HLL statement identifiers (or machine instruction numbers) at which tracing starts and, optionally, the identifier at which tracing stops. A maximum of five trace ranges can be defined at the same time for any program in debug mode. Each trace range begins with the specified starting statement, and all following statements are traced until the ending statement is reached. If only a starting statement identifier is specified for a range, the single statement specified is the only statement traced for that range. If machine instruction numbers are 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 and/or labels 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, or comments) following one another in a program. To determine which statements (labels) can be mapped to the same instruction, the intermediate representation of a program listing can be used.

Program variables (PGMVAR)

Specifies the names of the variables whose values are recorded when a trace statement in a program is processed. Depending on the value supplied for the When output (OUTVAR) parameter, the values can be recorded for every trace statement processed or only when a variable changes value. The program variables can be specified either by their high-level language names or by their machine-interface object-definition-table-vector (MI ODV) numbers.

Single values

*NONE

No program variables have their values recorded during tracing.

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 up to ten program variables whose values are recorded during tracing. If a variable name contains special characters, it must be enclosed in apostrophes.

If the program variable is an array, the subscripts representing the elements 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, blanks, parentheses, or commas. It does not include the enclosing apostrophes when special characters are used. An integer, MI ODV number, asterisk (single-dimensional cross-section), 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/.

Element 2: Basing pointer variable

character-value

Specify the names of up to five basing pointers for each program variable specified for element 1 of this parameter. 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 to be 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 qualifiers, subscripts, blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, 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 to use for recording the variables.

*CHAR

Variables are recorded in character form.

*HEX

Variables are recorded in hexadecimal form.

Program (PGM)

Specifies the program that contains the specified statement identifiers or the machine instruction numbers to trace.

*DFTPGM

The program previously specified as the default program contains the statements to trace.

name

Specify the name of the program that contains the statements to trace. The specified 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 recorded during tracing. 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. For a character string, the value specifies the starting character position.

1

The variable is recorded from the first position on through the length specified for the Characters to display (LEN) parameter.

integer

Specify the first position being recorded in the program variable.

The value supplied for the Char output start position (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 being recorded during the trace, starting at the position specified for the Char output start position (START) parameter. If more than one string variable is specified by 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.

*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 Characters to display (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 PGMVAR parameter.

When output (OUTVAR)

Specifies whether the values of the program variables are recorded only when their values change, or whether they are recorded regardless of any of their values being changed. This parameter is ignored if *NONE is specified or assumed for the Program variables (PGMVAR) parameter.

Note: Within each range, the values of all the traced variables are always recorded the first time a statement in the range is processed. The value supplied for the OUTVAR parameter determines when the variables are recorded for all following statements in the range.

*CHG

The system records the values of all the program variables when one or more of the values have changed since the last trace point. A variable is considered changed not only when its value is changed, but also when any of the displayed attributes change (such as length, lower and upper boundaries, and subscript values). For example, if an array is specified and the upper boundary changes for the array, the array is considered to have changed.

Note: The value might not appear to have changed if it contains characters that cannot be shown (a value less than 40 hex). The variable is still recorded even though you cannot see the change from what is shown. If *HEX is specified for the Output format (OUTFMT) parameter, the changes can be observed in the traced data.

*ALWAYS

The system records the values of the specified variables every time any of the specified trace statements are processed, whether or not any variable had its value changed.

Trace handling program (TRCPGM)

Specifies the user-supplied program that is called when a statement being traced is reached in the program specified on the Program (PGM) parameter. The program with the traced statement passes informational parameters to the trace-handling program when it is called. These parameters identify the program name, the recursion level, the high-level language statement identifier, the machine instruction number at which the trace statement occurred, and a changed variable indicator. The parameters have the following formats:

1. Program name (10 bytes). Specifies the name of the program in which the traced statement was reached.
2. Recursion level (5 bytes). Specifies the recursion level number of the program in which the traced statement was reached. This value is a 1- to 5-digit number padded on the right with blanks.
3. Statement Identifier (10 bytes). Specifies the high-level language program statement identifier that was reached. If the traced statement does not correspond to a statement identifier, the parameter contains a slash (/) followed by a 4-digit hexadecimal machine instruction number.
4. Instruction number (5 bytes). Specifies the machine instruction number that corresponds to the high-level language statement at which the traced statement was reached. No slash appears in front of the machine instruction number. The value consists of 1 to 4 hexadecimal characters representing the MI instruction number, followed by one or more blanks. If the program passes a machine instruction number on the third parameter, the values on the third and fourth parameters will be the same.

All the parameter values are left-justified and padded on the right with blanks. When control returns to the program with the traced statement, processing continues.

When a trace-handling program is specified and OUTVAR(*CHG) is specified, the trace-handling program is called only if a program variable specified on the Program variables (PGMVAR) parameter is changed. No trace data is recorded.

Single values

*NONE

No trace-handling program is called when a traced point specified on this command is reached in a batch environment. The interrupted program continues processing.

Qualifier 1: Trace handling program

name

Specify the name of the user-supplied program to be called when a traced statement is reached during debugging in a batch environment. The program specified must not be the same as the program specified on the Program (PGM) parameter. If the same program is specified for both the TRCPGM and PGM parameters, results can be unpredictable. After the program runs, control is returned to the interrupted program and processing continues.

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 searched. If no library is specified as the current library for the job, the QGPL library is used.

name

Specify the name of the library to be searched.

Examples

ADDTRC   STMT((100 120) (150 200))
         PGMVAR('&CTR' '&BRCTR' '&SAM')

This command traces program statements in the default program between the ranges of statements 100 through 120 and 150 through 200. Also, whenever the values of any of the program variables &CTR, &BRCTR, and &SAM are changed by one of the traced statements within those ranges, the values of all three are recorded before the traced statement is processed. When all of the traced statements have been processed, or when a breakpoint is reached, the Display Trace Data (DSPTRCDTA) command can be used to show the trace data collected.

Error messages

*ESCAPE Messages

CPF1999

Errors occurred on command.