Debugging C and C++ programs
Debug Tool commands that resemble C and C++ commands
Debug Tool's command language is a subset of C and C++ commands and has the same syntactical requirements. Debug Tool allows you to work in a language you are familiar with so learning a new set of commands is not necessary.The table below shows the interpretive subset of C and C++ commands recognized by Debug Tool.
| Command | Description |
|---|---|
| block ({}) | Composite command grouping |
| break | Termination of loops or switch commands |
| declarations | Declaration of session variables |
| do/while | Iterative looping |
| expression | Any C expression except the conditional (?) operator |
| for | Iterative looping |
| if | Conditional execution |
| switch | Conditional execution |
In addition to the subset of C and C++ commands that you can use is a list of reserved keywords used and recognized by C and C++ that you cannot abbreviate, use as variable names, or use as any other type of identifier.
Refer to the following topics for more information related to the material discussed in this topic.
- Related references
- C reserved keywords
- z/OS XL C/C++ Language Reference
Using C and C++ variables with Debug Tool
Debug Tool can process all program variables that are valid in C or C++. You can assign and display the values of variables during your session. You can also declare session variables with the recognized C declarations to suit your testing needs.Refer to the following topics for more information related to the material discussed in this topic.
- Related tasks
- Accessing C and C++ program variables
- Displaying values of C and C++ variables or expressions
- Assigning values to C and C++ variables
Accessing C and C++ program variables
Debug Tool obtains information about a program variable by name using the symbol table built by the compiler. If you specify TEST(SYM) at compile time, the compiler builds a symbol table that allows you to reference any variable in the program.
Note:
There are no suboptions for C++. Symbol information is
generated by default when the TEST compiler option is specified.
Refer to the following topics for more information related
to the material discussed in this topic.- Related tasks
- Preparing a C program
- Preparing a C++ program
Displaying values of C and C++ variables or expressions
To display the values of variables or expressions, use the LIST command. The LIST command causes Debug Tool to log and display the current values (and names, if requested) of variables, including the evaluated results of expressions.Suppose you want to display the program variables X, row[X], and col[X], and their values at line 25. If you issue the following command:
AT 25 LIST ( X, row[X], col[X] ); GO;
Debug Tool sets a breakpoint at line 25 (AT), begins execution
of the program (GO), stops at line 25, and displays the variable
names and their values.
If you want to see the result of their addition, enter: AT 25 LIST ( X + row[X] + col[X] ); GO;
Debug Tool sets a breakpoint at line 25 (AT), begins execution
of the program (GO), stops at line 25, and displays the result
of the expression.
Put commas between the variables when listing more than one. If you do
not want to display the variable names when issuing the LIST command,
enter LIST UNTITLED.You can also list variables with the printf function call as follows:
printf ("X=%d, row=%d, col=%d\n", X, row[X], col[X]);
The output from printf, however, does not appear in the
Log window and is not recorded in the log file unless you SET INTERCEPT
ON FILE stdout.
Assigning values to C and C++ variables
To assign a value to a C and C++ variable, you use an assignment expression. Assignment expressions assign a value to the left operand. The left operand must be a modifiable lvalue. An lvalue is an expression representing a data object that can be examined and altered.C contains two types of assignment operators: simple and compound. A simple assignment operator gives the value of the right operand to the left operand.
Note:
Only the assignment operators that work for C will work for C++,
that is, there is no support for overloaded operators.
The following example demonstrates how to assign the value of number to the member employee of the structure payroll: payroll.employee = number;Compound assignment operators perform an operation on both operands and give the result of that operation to the left operand. For example, this expression gives the value of index plus 2 to the variable index:
index += 2Debug Tool supports all C operators except the tenary operator, as well as any other full C language assignments and function calls to user or C library functions.
Refer to the following topics for more information related to the material discussed in this topic.
- Related tasks
- Calling C and C++ functions from Debug Tool
%PATHCODE values for C and C++
The table below shows the possible values for the Debug Tool variable %PATHCODE when the current programming language is C and C++.| -1 | Debug Tool is not in control as the result of a path or attention situation. |
| 0 | Attention function (not ATTENTION condition). |
| 1 | A block has been entered. |
| 2 | A block is about to be exited. |
| 3 | Control has reached a user label. |
| 4 | Control is being transferred as a result of a function reference. The invoked routine's parameters, if any, have been prepared. |
| 5 | Control is returning from a function reference. Any return code contained in register 15 has not yet been stored. |
| 6 | Some logic contained by a conditional do/while, for, or while statement is about to be executed. This can be a single or Null statement and not a block statement. |
| 7 | The logic following an if(...) is about to be executed. |
| 8 | The logic following an else is about to be executed. |
| 9 | The logic following a case within an switch is about to be executed. |
| 10 | The logic following a default within a switch is about to be executed. |
| 13 | The logic following the end of a switch, do, while, if(...), or for is about to be executed. |
| 17 | A goto, break, continue, or return is about to be executed. |
Declaring session variables with C and C++
You might want to declare session variables for use during the course of your session. You cannot initialize session variables in declarations. However, you can use an assignment statement or function call to initialize a session variable.As in C, keywords can be specified in any order. Variable names up to 255 characters in length can be used. Identifiers are case-sensitive, but if you want to use the session variable when the current programming language changes from C to another HLL, the variable must have an uppercase name and compatible attributes.
To declare a hexadecimal floating-point variable called maximum, enter the following C declaration:
double maximum;You can only declare scalars, arrays of scalars, structures, and unions in Debug Tool (pointers for the above are allowed as well).
If you declare a session variable with the same name as a programming variable, the session variable hides the programming variable. To reference the programming variable, you must qualify it. For example:
main:>x for the program variable x x for the session variable xSession variables remain in effect for the entire debug session, unless they are cleared using the CLEAR command.
Refer to the following topics for more information related to the material discussed in this topic.
- Related tasks
- Using session variables across different languages
- Qualifying variables and changing the point of view in C and C++
C and C++ expressions
Debug Tool allows evaluation of expressions in your test program. All expressions available in C and C++ are also available within Debug Tool except for the conditional expression (? :). That is, all operators such as +, -, %:, and += are fully supported with the exception of the conditional operator.C and C++ language expressions are arranged in the following groups based on the operators they contain and how you use them:
- Primary expression
- Unary expression
- Binary expression
- Conditional expression
- Assignment expression
- Comma expression
- lvalue
- Constant
The semantics for C and C++ operators are the same as in a compiled C or C++ program. Operands can be a mixture of constants (integer, floating-point, character, string, and enumeration), C and C++ variables, Debug Tool variables, or session variables declared during a Debug Tool session. Language constants are specified as described in the C and C++ Language Reference publications.
The Debug Tool command DESCRIBE ATTRIBUTES can be used to display the resultant type of an expression, without actually evaluating the expression.
The C and C++ language does not specify the order of evaluation for function call arguments. Consequently, it is possible for an expression to have a different execution sequence in compiled code than within Debug Tool. For example, if you enter the following in an interactive session:
int x;
int y;
x = y = 1;
printf ("%d %d %d%" x, y, x=y=0);
the results can differ from results produced by the same statements
located in a C or C++ program segment. Any expression containing behavior
undefined by ANSI standards can produce different results when evaluated by Debug Tool than
when evaluated by the compiler.
The following examples show you various ways Debug Tool supports the use of
expressions in your programs: - Debug Tool assigns 12 to a (the result of the printf())
function call, as in:
a = (1,2/3,a++,b++,printf("hello world\n")); - Debug Tool supports structure and array referencing and pointer dereferencing,
as in:
league[num].team[1].player[1]++; league[num].team[1].total += 1; ++(*pleague);
- Simple and compound assignment is supported, as in:
v.x = 3; a = b = c = d = 0; *(pointer++) -= 1;
- C and C++ language constants in expressions can be used, as in:
pointer_to_c = "abcdef" + 0x2; *pointer_to_long = 3521L = 0x69a1; float_val = 3e-11 + 6.6E-10; char_val = '7';
- The comma expression can be used, as in:
intensity <<= 1, shade * increment, rotate(direction); alpha = (y>>3, omega % 4);
- Debug Tool performs all implicit and explicit C conversions when necessary.
Conversion to long double is performed in:
long_double_val = unsigned_short_val; long_double_val = (long double) 3;
- Related references
- Debug Tool evaluation of C and C++ expressions
- z/OS XL C/C++ Language Reference
Calling C and C++ functions from Debug Tool
You can perform calls to user and C library functions within Debug Tool, unless your program was compiled with the FORMAT(DWARF) suboption of the DEBUG compiler option.You can make calls to C library functions at any time. In addition, you can use the C library variables stdin, stdout, stderr, __amrc, and errno in expressions including function calls.
The library function ctdli cannot be called unless it is referenced in a compile unit in the program, either main or a function linked to main.
Calls to user functions can be made, provided Debug Tool is able to locate an appropriate definition for the function within the symbol information in the user program. These definitions are created when the program is compiled with TEST(SYM) for C or TEST for C++.
Debug Tool performs parameter conversions and parameter-mismatch checking where possible. Parameter checking is performed if:
- The function is a library function
- A prototype for the function exists in the current compile unit
- Debug Tool is able to locate a prototype for the function in another compile unit, or the function itself was compiled with TEST(SYM) for C or with TEST for C++.
Calls can be made to any user functions that have linkage supported by the C or C++ compiler. However, for C++ calls made to any user function, the function must be declared as:
extern "C"
For example,
use this declaration if you want to debug an application signal handler.
When a condition occurs, control passes to Debug Tool which then passes control
to the signal handler.
Debug Tool attempts linkage checking, and does not perform the function call
if it determines there is a linkage mismatch. A linkage mismatch occurs when
the target program has one linkage but the source program believes it has
a different linkage.It is important to note the following regarding function calls:
- The evaluation order of function arguments can vary between the C and C++ program and Debug Tool. No discernible difference exists if the evaluation of arguments does not have side effects.
- Debug Tool knows about the function return value, and all the necessary conversions are performed when the return value is used in an expression.
- The functions cannot be in XPLINK applications.
- The functions must have debug information available.
- Related tasks
- Preparing a C program
- Preparing a C++ program
- Related references
- z/OS XL C/C++ Language Reference
C reserved keywords
The table below lists all keywords reserved by the C language. When the current programming language is C or C++, these keywords cannot be abbreviated, used as variable names, or used as any other type of identifiers.| auto | else | long | switch |
| break | enum | register | typedef |
| case | extern | return | union |
| char | float | short | unsigned |
| const | for | signed | void |
| continue | goto | sizeof | volatile |
| default | if | static | while |
| do | int | struct | _Packed |
| double |
C operators and operands
The table below lists the C language operators in order of precedence and shows the direction of associativity for each operator. The primary operators have the highest precedence. The comma operator has the lowest precedence. Operators in the same group have the same precedence.| Precedence level | Associativity | Operators |
|---|---|---|
| Primary | left to right | () [ ] . -> |
| Unary | right to left | ++ -- - + ! ~ & * (typename) sizeof |
| Multiplicative | left to right | * / % |
| Additive | left to right | + - |
| Bitwise shift | left to right | << >> |
| Relational | left to right | < > <= >= |
| Equality | left to right | ++ != |
| Bitwise logical AND | left to right | & |
| Bitwise exclusive OR | left to right | ^ or ¬ |
| Bitwise inclusive OR | left to right | | |
| Logical AND | left to right | && |
| Logical OR | left to right | || |
| Assignment | right to left | = += -= *= /= <<= >>= %= &= ^= |= |
| Comma | left to right | , |
Language Environment conditions and their C and C++ equivalents
Language Environment condition names (the symbolic feedback codes CEExxx) can be used interchangeably with the equivalent C and C++ conditions listed in the following table. For example, AT OCCURRENCE CEE341 is equivalent to AT OCCURRENCE SIGILL. Raising a CEE341 condition triggers an AT OCCURRENCE SIGILL breakpoint and vice versa.| Language Environment condition | Description | Equivalent C/C++ condition |
|---|---|---|
| CEE341 | Operation exception | SIGILL |
| CEE342 | Privileged operation exception | SIGILL |
| CEE343 | Execute exception | SIGILL |
| CEE344 | Protection exception | SIGSEGV |
| CEE345 | Addressing exception | SIGSEGV |
| CEE346 | Specification exception | SIGILL |
| CEE347 | Data exception | SIGFPE |
| CEE348 | Fixed point overflow exception | SIGFPE |
| CEE349 | Fixed point divide exception | SIGFPE |
| CEE34A | Decimal overflow exception | SIGFPE |
| CEE34B | Decimal divide exception | SIGFPE |
| CEE34C | Exponent overflow exception | SIGFPE |
| CEE34D | Exponent underflow exception | SIGFPE |
| CEE34E | Significance exception | SIGFPE |
| CEE34F | Floating-point divide exception | SIGFPE |
Debug Tool evaluation of C and C++ expressions
Debug Tool interprets most input as a collection of one or more expressions. You can use expressions to alter a program variable or to extend the program by adding expressions at points that are governed by AT breakpoints.Debug Tool evaluates C and C++ expressions following the rules presented in z/OS XL C/C++ Language Reference. The result of an expression is equal to the result that would have been produced if the same expression had been part of your compiled program.
Implicit string concatenation is supported. For example, "abc" "def" is accepted for "abcdef" and treated identically. Concatenation of wide string literals to string literals is not accepted. For example, L"abc"L"def" is valid and equivalent to L"abcdef", but "abc" L"def" is not valid.
Expressions you use during your session are evaluated with the same sensitivity to enablement as are compiled expressions. Conditions that are enabled are the same ones that exist for program statements.
During a Debug Tool session, if the current setting for WARNING is ON, the occurrence in your C or C++ program of any one of the conditions listed below causes the display of a diagnostic message.
- Division by zero
- Remainder (%) operator for a zero value in the second operand
- Array subscript out of bounds for a defined array
- Bit shifting by a number that is either negative or greater than 32
- Incorrect number of parameters, or parameter type mismatches for a function call
- Differing linkage calling conventions for a function call
- Assignment of an integer value to a variable of enumeration data type where the integer value does not correspond to an integer value of one of the enumeration constants of the enumeration data type
- Assignment to an lvalue that has the const attribute
- Attempt to take the address of an object with register storage class
- A signed integer constant not in the range -2**31 to 2**31
- A real constant not having an exponent of 3 or fewer digits
- A float constant not larger than 5.39796053469340278908664699142502496E-79 or smaller than 7.2370055773322622139731865630429929E+75
- A hex escape sequence that does not contain at least one hexadecimal digit
- An octal escape sequence with an integer value of 256 or greater
- An unsigned integer constant greater than the maximum value of 4294967295.
- Related references
- C and C++ expressions
- z/OS XL C/C++ Language Reference
Intercepting files when debugging C and C++ programs
Several considerations must be kept in mind when using the SET INTERCEPT command to intercept files while you are debugging a C application.For CICS(R) only: SET INTERCEPT is not supported for CICS.
For C++, there is no specific support for intercepting IOStreams. IOStreams is implemented using C I/O which implies that:
- If you intercept I/O for a C standard stream, this implicitly intercepts I/O for the corresponding IOStreams' standard stream.
- If you intercept I/O for a file, by name, and define an IOStream object associated with the same file, IOStream I/O to that file will be intercepted.
Note:
Although you can intercept IOStreams indirectly via C/370(TM) I/O, the behaviors
might be different or undefined in C++.
You can use the following names with the SET INTERCEPT command
during a debug session: - stdout, stderr, and stdin (lowercase only)
- any valid fopen() file specifier.
When a stream is intercepted, it inherits the text/binary attribute specified on the fopen statement. The output to and input from the Debug Tool log file behaves like terminal I/O, with the following considerations:
- Intercepted input behaves as though the terminal was opened for record I/O. Intercepted input is truncated if the data is longer than the record size and the truncated data is not available to subsequent reads.
- Intercepted output is not truncated. Data is split across multiple lines.
- Some situations causing an error with the real file might not cause an error when the file is intercepted (for example, truncation errors do not occur). Files expecting specific error conditions do not make good candidates for interception.
- Only sequential I/O can be performed on an intercepted stream, but file positioning functions are tolerated and the real file position is not changed. fseek, rewind, ftell, fgetpos, and fsetpos do not cause an error, but have no effect.
- The logical record length of an intercepted stream reflects the logical record length of the real file.
- When an unintercepted memory file is opened, the record format is always fixed and the open mode is always binary. These attributes are reflected in the intercepted stream.
- Files opened to the terminal for write are flushed before an input operation occurs from the terminal. This is not supported for intercepted files.
- When an fclose() occurs or INTERCEPT is set OFF for a file that was intercepted, the data is flushed to the session log file before the file is closed or the SET INTERCEPT OFF command is processed.
- When an fopen() occurs for an intercepted file, an open occurs on the real file before the interception takes effect. If the fopen() fails, no interception occurs for that file and any assumptions about the real file, such as the ddname allocation and data set defaults, take effect.
- The behavior of the ASIS suboption on the fopen() statement is not supported for intercepted files.
- When the clrmemf() function is invoked and memory files have been intercepted, the buffers are flushed to the session log file before the files are removed.
- If the fldata() function is invoked for an intercepted file, the characteristics of the real file are returned.
- If stderr is intercepted, the interception overrides the Language Environment message file (the default destination for stderr). A subsequent SET INTERCEPT OFF command returns stderr to its MSGFILE destination.
- If a file is opened with a ddname, interception occurs only if the ddname is specified on the INTERCEPT command. Intercepting the underlying file name does not cause interception of the stream.
- User prefix qualifications are included in MVS(TM) data set names entered in the INTERCEPT command, using the same rules as defined for the fopen() function.
- If library functions are invoked when Debug Tool is waiting for input for an intercepted file (for example, if you interactively enter fwrite(..) when Debug Tool is waiting for input), subsequent behavior is undefined.
- I/O intercepts remain in effect for the entire debug session, unless you terminate them by selecting SET INTERCEPT OFF.
- 1>&2
- If stderr is the target of the interception command, stdout is also intercepted. If stdout is the target of the INTERCEPT command, stderr is not intercepted. When INTERCEPT is set OFF for stdout, the stream is redirected to stderr.
- 2>&1
- If stdout is the target of the INTERCEPT command, stderr is also intercepted. If stderr is the target of the INTERCEPT command, stdout is not intercepted. When INTERCEPT is set OFF for stderr, the stream is redirected to stdout again.
- 1>file.name
- stdout is redirected to file.name. For interception of stdout to occur, stdout or file.name can be specified on the interception request. This also applies to 1>>file.name
- 2>file.name
- stderr is redirected to file.name. For interception of stderr to occur, stderr or file.name can be specified on the interception request. This also applies to 2>>file.name
- 2>&1 1>file.name
- stderr is redirected to stdout, and both are redirected to file.name. If file.name is specified on the interception command, both stderr and stdout are intercepted. If you specify stderr or stdout on the INTERCEPT command, the behavior follows rule 1b above.
- 1>&2 2>file.name
- stdout is redirected to stderr, and both are redirected to file.name. If you specify file.name on the INTERCEPT command, both stderr and stdout are intercepted. If you specify stdout or stderr on the INTERCEPT command, the behavior follows rule 1a above.
- 2>&1 2>file.name
- Behavior of stderr is undefined.
- 1>&2 1>file.name
- Behavior of stdout is undefined.
- Related references
- z/OS XL C/C++ Programming Guide
Scope of objects in C and C++
An object is visible in a block or source file if its data type and declared name are known within the block or source file. The region where an object is visible is referred to as its scope. In Debug Tool, an object can be a variable or function and is also used to refer to line numbers.
Note:
The use of an object here is not to be confused with a C++ object.
Any reference to C++ will be qualified as such.
In ANSI C, the four kinds of scope are: - Block
- File
- Function
- Function prototype
An object has block scope if its declaration is located inside a block. An object with block scope is visible from the point where it is declared to the closing brace (}) that terminates the block.
An object has file scope if its definition appears outside of any block. Such an object is visible from the point where it is declared to the end of the source file. In Debug Tool, if you are qualified to the compilation unit with the file static variables, file static and global variables are always visible.
The only type of object with function scope is a label name.
An object has function prototype scope if its declaration appears within the list of parameters in a function prototype.
A class member has class scope if its declaration is located inside a class.
You cannot reference objects that are visible at function prototype scope, but you can reference ones that are visible at file or block scope if:
- For C variables and functions, the source file was compiled with TEST(SYM) and the object was referenced somewhere within the source.
- For C variables declared in a block that is nested in another block, the source file was compiled with TEST(SYM, BLOCK).
- For line numbers, the source file was compiled with TEST(LINE) GONUMBER.
- For labels, the source file was compiled with TEST(SYM, PATH). In some cases (for example, when using GOTO), labels can be referenced if the source file was compiled with TEST(SYM, NOPATH).
In addition, Debug Tool supports the referencing of variables in multiple load modules. Multiple load modules are managed through the C library functions dllload(), dllfree(), fetch(), and release().
Example: referencing variables and setting breakpoints in C and C++ blocks
- Related concepts
- Storage classes in C and C++
Storage classes in C and C++
Debug Tool supports the change and reference of all objects declared with the following storage classes:- auto
- register
- static
- extern
An object with auto storage class is available for reference or change in Debug Tool, provided the block where it is defined is active. Once a block finishes executing, the auto variables within this block are no longer available for change, but can still be examined using DESCRIBE ATTRIBUTES.
An object with register storage class might be available for reference or change in Debug Tool, provided the variable has not been optimized to a register.
An object with static storage class is always available for change or reference in Debug Tool. If it is not located in the currently qualified compile unit, you must specifically qualify it.
An object with extern storage class is always available for change or reference in Debug Tool. It might also be possible to reference such a variable in a program even if it is not defined or referenced from within this source file. This is possible provided Debug Tool can locate another compile unit (compiled with TEST(SYM)) with the appropriate definition.
Blocks and block identifiers for C
It is often necessary to set breakpoints on entry into or exit from a given block or to reference variables that are not immediately visible from the current block. Debug Tool can do this, provided that all blocks are named. It uses the following naming convention:- The outermost block of a function has the same name as the function.
- Blocks enclosed in this outermost block are sequentially named: %BLOCK2, %BLOCK3, %BLOCK4, and so on in order of their appearance in the function.
- Short form
- function_name:>%BLOCKzzz
- Long form
- function_name:>%BLOCKxxx :>%BLOCKyyy: ... :>%BLOCKzzz
The currently active block name can be retrieved from the Debug Tool variable %BLOCK. You can display the names of blocks by entering:
DESCRIBE CU;
Blocks and block identifiers for C++
Block Identifiers tend to be longer for C++ than C because C++ functions can be overloaded. In order to distinguish one function name from the other, each block identifier is like a prototype. For example, a function named shapes(int,int) in C would have a block named shapes; however, in C++ the block would be called shapes(int,int).You must always refer to a C++ block identifier in its entirety, even if the function is not overloaded. That is, you cannot refer to shapes(int,int) as shapes only.
Note:
The block name for main() is always main (without
the qualifying parameters after it) even when compiled with C++ because main() has extern C linkage.
Since block names can be quite long, it is not unusual to see the name
truncated in the LOCATION field on the first line of the screen.
If you want to find out where you are, enter: QUERY LOCATION
and the name will be shown in its entirety (wrapped) in the session log.
Block identifiers are restricted to a length of 255 characters. Any name
longer than 255 characters is truncated.Example: referencing variables and setting breakpoints in C and C++ blocks
The program below is used as the basis for several examples, described after the program listing.#pragma runopts(EXECOPS)
#include <stdlib.h>
main()
{
>>> Debug Tool is given <<<
>>> control here. <<<
init();
sort();
}
short length = 40;
static long *table;
init()
{
table = malloc(sizeof(long)*length);
·
·
·
}
sort ()
{ /* Block sort */
int i;
for (i = 0; i < length-1; i++) { /* Block %BLOCK2 */
int j;
for (j = i+1; j < length; j++) { /* Block %BLOCK3 */
static int temp;
temp = table[i];
table[i] = table[j];
table[j] = temp;
}
}
}
Scope and visibility of objects
Let's assume the program shown above is compiled with TEST(SYM). When Debug Tool gains control, the file scope variables length and table are available for change, as in:length = 60;The block scope variables i, j, and temp are not visible in this scope and cannot be directly referenced from within Debug Tool at this time. You can list the line numbers in the current scope by entering:
LIST LINE NUMBERS;Now let's assume the program is compiled with TEST(SYM, NOBLOCK). Since the program is explicitly compiled using NOBLOCK, Debug Tool will never know about the variables j and temp because they are defined in a block that is nested in another block. Debug Tool does know about the variable i since it is not in a scope that is nested.
Blocks and block identifiers
In the program above, the function sort has three blocks:- sort
- %BLOCK2
- %BLOCK3
at entry sort:>%BLOCK2;The following example sets a breakpoint on exit of the first block of main and lists the entries of the sorted table.
at exit main {
for (i = 0; i < length; i++)
printf("table entry %d is %d\n", i, table[i]);
}
The following example lists the variable temp in the third block
of sort. This is possible since temp has the static storage class. LIST sort:>%BLOCK3:temp;
Displaying environmental information
You can also use the DESCRIBE command to display a list of attributes applicable to the current run-time environment. The type of information displayed varies from language to language.Issuing DESCRIBE ENVIRONMENT displays a list of open files and conditions being monitored by the run-time environment. For example, if you enter DESCRIBE ENVIRONMENT while debugging a C or C++ program, you might get the following output:
Currently open files
stdout
sysprint
The following conditions are enabled:
SIGFPE
SIGILL
SIGSEGV
SIGTERM
SIGINT
SIGABRT
SIGUSR1
SIGUSR2
SIGABND
Qualifying variables and changing the point of view in C and C++
Qualification is a method of:- Specifying an object through the use of qualifiers
- Changing the point of view
When program execution is suspended and Debug Tool receives control, the default, or implicit qualification is the active block at the point of program suspension. All objects visible to the C or C++ program in this block are also visible to Debug Tool. Such objects can be specified in commands without the use of qualifiers. All others must be specified using explicit qualification.
Qualifiers depend, of course, upon the naming convention of the system where you are working.
Example: using qualification in C
Qualifying variables in C and C++
You can precisely specify an object, provided you know the following:- Load module or DLL name
- Source file (compilation unit) name
- Block name (must include function prototype for C++ block qualification).
load_name::>cu_name:>block_name:>objectIf required, load_name is the name of the load module. It is required only when the program consists of multiple load modules and when you want to change the qualification to other than the current load module. load_name is enclosed in quotation marks ("). If it is not, it must be a valid identifier in the C or C++ programming language. load_name can also be the Debug Tool variable %LOAD.
If required, CU_NAME is the name of the compilation unit or source file. The cu_name must be the fully qualified source file name or an absolute pathname. It is required only when you want to change the qualification to other than the currently qualified compilation unit. It can be the Debug Tool variable %CU. If there appears to be an ambiguity between the compilation unit name, and (for example), a block name, you must enclose the compilation unit name in quotation marks (").
If required, block_name is the name of the block. block_name can be the Debug Tool variable %BLOCK.
Example: using qualification in C
Refer to the following topics for more information related to the material discussed in this topic.
- Related concepts
- Blocks and block identifiers for C
Changing the point of view in C and C++
To change the point of view from the command line or a commands file, use qualifiers in conjunction with the SET QUALIFY command. This can be necessary to get to data that is inaccessible from the current point of view, or can simplify debugging when a number of objects are being referenced.It is possible to change the point of view to another load module or DLL, to another compilation unit, to a nested block, or to a block that is not nested. The SET keyword is optional.
Example: using qualification in C
Example: using qualification in C
The examples below use the following program.LOAD MODULE NAME: MAINMOD
SOURCE FILE NAME: MVSID.SORTMAIN.C
short length = 40;
main ()
{
long *table;
void (*pf)();
table = malloc(sizeof(long)*length);
·
·
·
pf = fetch("SORTMOD");
(*pf)(table);
·
·
·
release(pf);
·
·
·
}
LOAD MODULE NAME: SORTMOD
SOURCE FILE NAME: MVSID.SORTSUB.C
short length = 40;
short sn = 3;
void (long table[])
{
short i;
for (i = 0; i < length-1; i++) {
short j;
for (j = i+1; j < length; j++) {
float sn = 3.0;
short temp;
temp = table[i];
·
·
·
>>> Debug Tool is given <<<
>>> control here. <<<
·
·
·
table[i] = table[j];
table[j] = temp;
}
}
}
When Debug Tool receives control, variables i, j, temp, table, and length can be specified without
qualifiers in a command. If variable sn is referenced, Debug Tool uses
the variable that is a float. However, the names of the blocks
and compile units differ, maintaining compatibility with the operating system.Qualifying variables
- Change the file scope variable length defined in the compilation
unit MVSID.SORTSUB.C in the load module SORTMOD:
"SORTMOD"::>"MVSID.SORTSUB.C":>length = 20;
- Assume Debug Tool gained control from main(). The following changes
the variable length:
%LOAD::>"MVSID.SORTMAIN.C":>length = 20;
Because length is in the current load module and compilation unit, it can also be changed by:
length = 20;
- Assume Debug Tool gained control as shown in the example program above. You
can break whenever the variable temp in load module SORTMOD changes
in any of the following ways:
AT CHANGE temp; AT CHANGE %BLOCK3:>temp; AT CHANGE sort:%BLOCK3:>temp; AT CHANGE %BLOCK:>temp; AT CHANGE %CU:>sort:>%BLOCK3:>temp; AT CHANGE "MVSID.SORTSUB.C":>sort:>%BLOCK3:>temp; AT CHANGE "SORTMOD"::>"MVSID.SORTSUB.C":>sort:>%BLOCK3:>temp;
Changing the point of view
- Qualify to the second nested block in the function sort() in sort.
SET QUALIFY BLOCK %BLOCK2;
You can do this in a number of other ways, including:QUALIFY BLOCK sort:>%BLOCK2;
Once the point of view changes, Debug Tool has access to objects accessible from this point of view. You can specify these objects in commands without qualifiers, as in:
j = 3; temp = 4;
- Qualify to the function main in the load module MAINMOD in
the compilation unit MVSID.SORTMAIN.C and list the entries of table.
QUALIFY BLOCK "MAINMOD"::>"MVSID.SORTMAIN.C":>main; LIST table[i];
Stepping through C++ programs
You can step through methods as objects are constructed and destructed. In addition, you can step through static constructors and destructors. These are methods of objects that are executed before and after main() respectively.If you are debugging a program that calls a function that resides in a header file, the cursor moves to the applicable header file. You can then view the function source as you step through it. Once the function returns, debugging continues at the line following the original function call.
You can step around a header file function by issuing the STEP OVER command. This is useful in stepping over Library functions (for example, string functions defined in string.h) that you cannot debug anyway.
Setting breakpoints in C++
The differences between setting breakpoints in C++ and C are described below.Setting breakpoints in C++ using AT ENTRY/EXIT
AT ENTRY/EXIT sets a breakpoint in the specified block. You can set a breakpoint on methods, methods within nested classes, templates, and overloaded operators. An example is given for each below.A block identifier can be quite long, especially with templates, nested classes, or class with many levels of inheritance. In fact, it might not even be obvious at first as to the block name for a particular function. To set a breakpoint for these nontrivial blocks can be quite cumbersome. Therefore, it is recommended that you make use of DESCRIBE CU and retrieve the block identifier from the session log.
When you do a DESCRIBE CU, the methods are always shown qualified by their class. If a method is unique, you can set a breakpoint by using just the method name. Otherwise, you must qualify the method with its class name. The following two examples are equivalent:
AT ENTRY method() AT ENTRY classname::method()The following examples are valid:
| AT ENTRY square(int,int) | 'simple' method square |
| AT ENTRY shapes::square(int) | Method square qualified by its class shapes. |
| AT EXIT outer::inner::func() | Nested classes. Outer and inner are classes. func() is within class inner. |
| AT EXIT Stack<int,5>::Stack() | Templates. |
| AT ENTRY Plus::operator++(int) | Overloaded operator. |
| AT ENTRY ::fail() | Functions defined at file scope must be referenced by the global scope operator :: |
| AT ENTRY shapes | Where shapes is a class. Cannot set breakpoint on a class. (There is no block identifier for a class.) |
| AT ENTRY shapes::square | Invalid since method square must be followed by its parameter list. |
| AT ENTRY shapes:>square(int) | Invalid since shapes is a class name, not a block name. |
Setting breakpoints in C++ using AT CALL
AT CALL gives Debug Tool control when the application code attempts to call the specified entry point. The entry name must be a fully qualified name. That is, the name shown in DESCRIBE CU must be used. Using the exampleAT ENTRY shapes::square(int)
to set a breakpoint
on the method square, you must enter:
AT CALL shapes::square(int)Refer to the following topics for more information related to the material discussed in this topic.
Examining C++ objects
When displaying an C++ object, only the local member variables are shown. Access types (public, private, protected) are not distinguished among the variables. The member functions are not displayed. If you want to see their attributes, you can display them individually, but not in the context of a class. When displaying a derived class, the base class within it is shown as type class and will not be expanded.Refer to the following topics for more information related to the material discussed in this topic.
- Related tasks
- Example: displaying attributes of C++ objects
Example: displaying attributes of C++ objects
The examples below use the following definitions.class shape { ... };
class line : public shape {
member variables of class line...
}
line edge;
Displaying object attributes
To describe the attributes of the object edge, enter the following command.DESCRIBE ATTRIBUTES edge;The Log window displays the following output.
DESCRIBE ATTRIBUTES edge;
ATTRIBUTES for edge
Its address is yyyyyyyy and its length is xx
class line
class shape
member variables of class shape....
Note that the base class is shown as class shape _shape.Displaying class attributes
To display the attributes of class shape, enter the following command.DESCRIBE ATTRIBUTES class shape;The Log window displays the following output.
DESCRIBE ATTRIBUTES class shape ; ATTRIBUTES for class shape const class shape...
Displaying static data
If a class contains static data, the static data will be shown as part of the class when displayed. For example:class A {
int x;
static int y;
}
A obj;
You can also display the static member by referencing it as A::y since each object of class A has the same value.
Displaying global data
To avoid ambiguity, variables declared at file scope can be referenced using the global scope operator ::. For example:int x;
class A {
int x;
·
·
·
}
}
If you are within a member function of A and want to display the value
of x at file scope, enter LIST ::x. If you do not use ::, entering LIST x will display the value of x for the current object
(i.e., this->x).Monitoring storage in C++
You might find it useful to monitor registers (general-purpose and floating-point) while stepping through your code and assembly listing by using the LIST REGISTERS command. The compiler listing displays the pseudo assembly code, including Debug Tool hooks. You can watch the hooks that you stop on and watch expected changes in register values step by step in accordance with the pseudo assembly instructions between the hooks. You can also modify the value of machine registers while stepping through your code.You can list the contents of storage in various ways. Using the LIST REGISTERS command, you can receive a list of the contents of the General Purpose Registers or the floating-point registers.
You can also monitor the contents of storage by specifying a dump-format display of storage. To accomplish this, use the LIST STORAGE command. You can specify the address of the storage that you want to view, as well as the number of bytes.
Example: monitoring and modifying registers and storage in C
The examples below use the following C program to demonstrate how to monitor and modify registers and storage.int dbl(int j) /* line 1 */
{ /* line 2 */
return 2*j; /* line 3 */
} /* line 4 */
int main(void)
{
int i;
i = 10;
return dbl(i);
}
If you compile the program above using the compiler options TEST(ALL),LIST, then your pseudo assembly listing will be similar to the listing shown
below. * int dbl(int j)
ST r1,152(,r13)
* {
EX r0,HOOK..PGM-ENTRY
* return 2*j;
EX r0,HOOK..STMT
L r15,152(,r13)
L r15,0(,r15)
SLL r15,1
B @5L2
DC A@5L2-ep)
NOPR
@5L1 DS 0D
* }
@5L2 DS 0D
EX r0,HOOK..PGM-EXIT
To display a continuously updated view of the registers in the Monitor
window, enter the following command: MONITOR LIST REGISTERSAfter a few steps, Debug Tool halts on line 1 (the program entry hook, shown in the listing above). Another STEP takes you to line 3, and halts on the statement hook. The next STEP takes you to line 4, and halts on the program exit hook. As indicated by the pseudo assembly listing, only register 15 has changed during this STEP, and it contains the return value of the function. In the Monitor window, register 15 now has the value 0x00000014 (decimal 20), as expected.
You can change the value from 20 to 8 just before returning from dbl() by issuing the command:
%GPR15 = 8 ;
No comments:
Post a Comment