TotalView Online Help : Chapter 3 Variable Window
Chapter 3 Variable Window
Variable Window Overview
The Variable Window displays information about one of your program’s objects.
This window is more than just a viewer. It lets you change a variable or element’s value, as well as allowing you a variety of ways to alter what TotalView is displaying. For example, you can cast a variable to the way you want it to appear.
The type mapping procedure lets you control how TotalView displays information.
For more information, see "Changing How Data is Displayed" in the TotalView for HPC User Guide. On creating your own transformations, see "Creating Type Transformations" in the TotalView for HPC Reference Guide.
Figure 91 – Variable Window
Other examples of changes you can make are:
If TotalView is displaying an array, you can display a limited section of the array, called a slice, instead of the whole array.
You can also enter a filter that tells TotalView to make decisions about which array elements it should display.
Topics here are:
"Expression Field—Altering What is Being Displayed"
"Address Field—Changing a Variable’s Address"
"Status Field—Seeing State and Error Messages"
"Type Field—Changing a Variable or Element’s Data Type"
"Slice Field—Altering Subscripts"
"Filter Field—Filtering Array Values"
Other operations you can perform are described in the following sections.
"Diving into Elements"
"Sorting Columns"
"Changing the Process and Thread"
When you tell TotalView to open a Variable Window, it tries to find a window that is already displaying the element. If it finds one, TotalView moves this window to the front of the display.
If the variable or element being displayed contains substructures, only the name of the substructure is immediately visible. To display a substructure, click on the +” icon. Clicking on the “-” icon closes the substructure, hiding the information. You can use the View > Expand all and View > Collapse All commands to expand and collapse all trees.
Expression Field—Altering What is Being Displayed
When TotalView first displays a Variable Window, the value of the Expression field contains a variable, element, or expression. The exact contents depend upon what you dove on or what was entered in a View > Lookup Variable command.
By changing this field’s text, you can change what is displayed. For example, if the expression contained the variable my_var, you could change this to my_var.struct1.substruct1[3].
As the name of this field implies, you can type an expression in this field. For example, you could type either i+3 or my_var[i+3]. You cannot, however, enter an expression that contains a function call or an expression that has a side-effect. For example, you could not enter my_var[i++].
Address Field—Changing a Variable’s Address
To view a different part of memory, edit the Address field in the upper left corner of the window. If TotalView needs to display information about an address, it displays this information in the unlabeled field to the right of the Address field. Note, however, that you cannot change the address of register variables.
Type Field—Changing a Variable or Element’s Data Type
To change the data type that TotalView uses to format the variable, edit the text within the Type field.
While you cannot directly edit the type entry for a field in a substructure, you can dive into the substructure and then edit it.
More and Less Buttons
TotalView usually displays information about your variable in addition to the array’s value. This information is sometimes called meta-information. You can control how much of this meta-information it displays by clicking on the More and Less buttons. For example:
Figure 92 – More and Less Buttons
As the button names indicate, clicking More displays more meta-information and clicking Less displays less of it. The following list describes the purpose of these fields.
Contains the variable’s data type. This field contains the same information that appears when TotalView is not showing you more information. However, if the name is very long, you’ll be able to see its entire name here.
Actual Type
If the Variable Window is showing a Fortran assumed shape array, the Type field contains the current array definition. The Actual Type field shows how the array was declared.
The programming language used for the currently scoped expression or variable.
Valid in Scope
Indicates the scope in which the variable resides. That is, the variable is “valid” anytime the PC is within this scope. If you display the pulldown list, you will see the complete scope specification.
Compiled in Scope
Indicates the scope in which the expression was compiled. If you alter the text within the Expression field of the Variable Window, this field lets you know the scope where the expression is defined. If you display the pulldown list, you will see the complete scope specification.
Status Field—Seeing State and Error Messages
If a problem occurs when you make a change to a field or if TotalView needs to tell you something about this window’s contents, it will display information here.
For example, if a variable is no longer in scope—that is, your program is no longer executing in a scope in which the variable is defined—TotalView tells you that the variable is stale.
Slice Field—Altering Subscripts
To change an array’s subscripts, edit the data that appears after the Slice: field at the top of the window. You can enter each array dimension by using one of the following formats, depending upon your programming language:
(slice descriptor,slice descriptor,...)
[slice descriptor][slice descriptor]...
The slice descriptor tells TotalView that it should display every strideth subscript from the lower bound to the upper bound, inclusive. If the stride is negative, TotalView shows every -strideth subscript from the upper bound to the lower bound, inclusive, in reverse order.
Each Slice field has a lower bound, an upper bound, and a stride. These elements are separated by a colon (:).
If you omit the stride value and its colon separator, the default stride value is 1. If you omit the upper bounds, the lower bounds value will be the upper bounds value. The lower bound must be less than or equal to the upper bound, and the stride cannot be 0.
Filter Field—Filtering Array Values
You can tell TotalView that it should selectively display information from the array by entering a value in the Filter field.
While there are a number of ways to specify a filter, the general format is:
operator value
where operator is one or more of the following:
<, <=, >, >=, ==, !=
.lt. .le. .gt. .ge. .eq. .ne.
value can be a constant integer or real value. For example:
> 0
You can also enter a TotalView intrinsic, which is a built-in representation of IEEE floating-point NaN (Not a Number), INF (infinity), or denormalized value. These intrinsics are:
any NaN (Not a Number)
quiet NaN (Not a Number)
signaling NaN (Not a Number)
any INF, either positive or negative
negative INF
positive INF
denormalized number, either positive or negative
positive denormalized number
negative denormalized number
NOTE >> You can only use the == and != operators with these intrinsics. For example, != $denorm.
You can add a second component to the filter to indicate that TotalView should show elements contained within a range by using the following format:
Here are some points to consider:
low_value and high_value are constant integers or real values.
You can apply the < and > operators to the low and high values to allow for exclusive ranges. By default, the range is inclusive of the lower and upper values.
low_value and high_value cannot be of different types. For example, the following range is invalid:
You can use the $value token to represent the current array element. For example:
$value > 0 && $value < 100
This filter expression tells TotalView to displays all array elements that are greater than 0 and less than 100.
Your filter can also contain program variables. For example:
$value != x && $value < y
You cannot use function calls in a filter expression.
For more information, see Setting Action Points in the TotalView Users Guide.
Changing the Value of a Variable
To change the value of a simple variable or change the value of a field in a more complex variable (a structure or array), click the cursor within the variable or element’s value, then enter the changed value.
Diving into Elements
To view the target of a pointer or to view one element in an array or structure, double-click on the entry. TotalView replaces the contents of the window with a view of the item you dived into (or the object it points to, in the case of pointers). This allows you to easily chase chains of linked structures.
After you dive into a field, you can edit its contents. (Diving into a substructure is the only way to edit the substructure’s value.) You can also cast individual entries in arrays to different data types for display.
Sorting Columns
If you are viewing an array, you can sort the array’s value by clicking on the Value heading.
Clicking once on Value sorts the array into ascending order.
Clicking again sorts the array into descending order.
Clicking a third time returns the order to what it was before you clicked on the Value heading.
The hierarchy button () within the heading allows you to change the Variable Window’s display from a flat view to a hierarchical view. When displayed hierarchically, you can use the + and - minus buttons to expand and contract similar groups of information in the display. As you click on headings, you are telling TotalView to aggregate the information in a different way. This means you can create different information groupings.
When you are displaying in formation in its flat view, aggregation does not occur when you sort information by clicking on a column heading.
Changing the Process and Thread
The process/thread box initially indicates the variable or element’s context when you created the Variable Window. You can change this context be either typing in a new process/thread number (be sure to separate the process number from the thread number with a period) or selecting a value from the pulldown list.
Seeing Variable Value Changes
TotalView can tell you when a variable’s value changes in several ways.
When your program stops at a breakpoint, TotalView adds a yellow highlight to the variable’s value if it has changed.
Figure 93 – Variable Window With “Change” Highlighting
If the thread is stopped for another reason—for example, you’ve stepped the thread—and the value has changed, TotalView does not add yellow highlighting to the line.
You can tell TotalView to display the Last Value column. Do this by selecting Last Value in the column menu, which is displayed after you click on the column menu () icon.
Figure 94 – Variable Window Showing Last Value Column
Notice that TotalView has highlighted all items that have changed within an array. In a similar fashion it can show the individual items that have changed within a structure.
NOTE >> When you scroll the Variable Window, TotalView discards the information it is tracking and fetches new information. So, while the values may have changed, TotalView does not have information about this change. That is, TotalView only tracks what it is visible. Similarly, when you scroll back to previously displayed values, TotalView needs to refetch this information. Because it is “new” information, no “last values” exist.
The Expression List window, also highlights data and can display a Last Value column.
related topics
Examining and Changing Data
Displaying Array Slices
Array Data Filtering
Changing a Variable’s Data Type
Changing the Address of Variables