See Chapter 6, Collection Grids and Lists for a complete description of the procedures you can use to customize collection grids and of other collection grid features.

Navigating Instances

Navigation is the process of following relationships from one instance to another. When you navigate instances, Inspector records the resulting navigation tree in the Navigation window.

This section describes the different ways you can navigate instances and the features of the Navigation window.

For more information: You can also locate an instance based on its address or segment offset. See Tools for Debugging.

Two Ways to Navigate

There are two ways to navigate instances:

Manually - When you navigate manually, you choose your own navigation path through the database by navigating from instance to instance, one instance at a time. You can navigate to any instance you choose. Manual navigation can originate only from the Instance window.
Automatically - You can use Inspector's Auto Navigate feature to quickly display all the instances related to the one you have selected. In addition, you can perform Auto Navigation from any place an instance is displayed. Note, however, that Inspector is able to autonavigate recognized relationships only. See Navigating Automatically for more information.

How to Navigate Manually

To navigate manually:

Open an Instance window for the instance whose relationships you want to navigate.

Tip: See How to open the Instance window if you need help.
Place the pointer on the related instance to which you want to navigate.

Tip: The pointer changes to a magnifying glass when it is placed on a navigable instance.
Double-click to navigate to that instance.

A new Instance window appears, displaying information for the instance to which you just navigated.
In addition, Inspector opens a Navigation window that records the path to each instance you navigate. The window is minimized and appears in the lower left corner of the Inspector workspace.
Repeat step 2 and step 3 to navigate to other related instances.

Navigating Automatically

Recognizing relationships

When you use automatic navigation, Inspector navigates only recognized relationships. A recognized relationship is one that is either

Defined as part of the database,
Created by Inspector

For more information on how Inspector works with ObjectStore relationships, see Identifying Relationships Between Classes.

How to navigate automatically

To navigate all related instances automatically:

Select the instance you want to navigate.
Click Navigation | Auto Navigate from the menu bar, or click Auto Navigate on the instance shortcut menu.

Alternative: Press the Ctrl key and click the instance you want to automatically navigate.
Inspector opens a Navigation window that displays all navigable instances of the instance you selected in step 1.

About the Navigation Window

The Navigation window helps you keep track of the instance relationships you have navigated, whether manually, from the Instance window, or automatically, using the Auto Navigate feature.

Navigation window symbols

The Navigation window displays symbols that represent

Instances - The initial instance appears on the left side of the Navigation window. Subsequent instances follow, from left to right. An instance that is part of a one-to-many or many-to-many relationship is displayed in a collection list box containing the related instances. If an instance appears with a shaded background, it means that instance's Instance window is no longer open.
Tip: Remember that you control how instances are represented (icons, which data members are shown, and so on) using the Instance Format dialog box. See Customizing the Instance Display for more information.
Relationships - Relationships between instances are represented with arrows that point from the source instance to the one to which it is related, from left to right.
Data members - The names of the data members used to establish the relationship are displayed alongside the instance with which the data member is associated.

Formatting navigation trees

You might want to consider changing the following characteristics of the navigation tree before printing a Navigation window.

Path layout - The Path Layout dialog box lets you control the horizontal and vertical space between instances. The value controlling vertical spacing must be between 60 and 300, inclusive. The value controlling horizontal spacing must be between 10 and 200, inclusive.
To display the Path Layout dialog box, click Navigation | Set Path Layout from the menu bar, or Set Path Layout from the Navigation window shortcut menu.
Navigation tree layout - You use the Center Tree command to center the entire navigation tree within the Navigation window. To perform the Center Tree command, click Navigation | Center Tree from the menu bar, or Center Tree from the Navigation window shortcut menu.

For more information: To learn more about printing Inspector information, see Appendix A, Printing.

Saving navigation trees

One of the benefits of the Navigation window is that it records the path you have taken through the database while inspecting classes and their instances. Because object databases can be complex, it can be valuable for you to be able to save the tree resulting from a particular navigation session, regardless of whether you created it manually or automatically.

To save a navigation tree:

Click File | Save on the menu bar.

The Save Navigation Tree dialog box opens.
Name the navigation tree and click Save.

The navigation tree is saved with the database.

Opening a navigation tree

To open a navigation tree you have saved previously:

Click Navigation | Open Navigation Tree on the menu bar.

The Open Navigation Tree dialog box appears.
Tip: The Open Navigation Tree dialog box is similar to the Save Navigation Tree dialog box.
The list box displays all the navigation trees associated with the current database.
Select the navigation tree you want to open from the list box and click the OK button.

Alternative: Double-click the navigation tree name.
The Navigation window containing the navigation tree you selected appears.

Deleting a navigation tree

To delete a navigation tree:

Click Navigation | Delete on the menu bar.

The Delete Navigation Tree dialog box appears.
Tip: The Delete Navigation Tree dialog box is similar to the Save Navigation Tree dialog box.
The list box displays all the navigation trees associated with the current database.
Select the navigation tree you want to delete from the list box and click the Delete button.

Other Navigation window features

In addition to the layout features already described, you can use the Navigation window shortcut menu to

Open and close an Instance window
Close all open Instance windows associated with instances in the navigation tree
Perform another auto navigation task

Navigation Options

The Navigation page of the Options dialog box contains default settings for preferences for Navigation windows.

Choices on the Navigation page let you set default values for

Navigation tree formatting characteristics
Handling open Instance windows when quitting a navigation session
Handling open Navigation windows related to the current Navigation window when quitting a navigation session

To learn more about Inspector options, see Inspector Options.

Identifying Relationships Between Classes

You typically create a relationship between two classes as part of defining an ObjectStore database. Among other things, the presence of these relationships enables Inspector to autonavigate from one class to another.

This section describes how Inspector uses information that is not part of the schema definition to identify relationships in an ObjectStore database.

Inspector Creates Some Relationships Automatically

Inspector creates a relationship between two classes when one class, say ServiceItem, contains a data member that is a templated ObjectStore collection or os_reference consisting of instances from another class, say QuPart. By definition, these collections consist of a homogeneous set of instances, making the relationship between the two classes meaningful.

Inspector Identifies Possible Relationships

If WorkOrder, on the other hand, is a nontemplated collection or a nontemplated os_reference, Inspector first reviews the collection's instances. If it determines that all of the instances are of the same type, it displays the following dialog box, suggesting that a possible relationship exists and giving you the opportunity to create it.

Click Yes to establish relationships between the two classes shown in the dialog box. If you click No, you can create the relationship later as follows.

In the Schema Pane right click on a class and select Examine Relationships from the shortcut menu. The Examine Oneway Relationships dialog box is displayed showing relationships that have already been created as well as possible relationships that have not yet been created.
Click on the checkbox next to the relationship you want to create.

Relationships Between Java Classes

In Java databases, Inspector automatically creates a one-way relationship between the abstract class Object and a subclass when the subclass has a field with a collection data type such as com.odi.coll.set. (ObjectStore maps the class os_dma_singleton to the Java class Object

In this example, a one-way relationship between Customer and Object is created based on the myCars field in the Customer class, which has the type com.odi.coll.set.

If you then open an instance of Customer, Inspector identifies a possible relationship between Customer and Cars. If you decide to create this relationship, Inspector removes the relationship it created between Customer and Object, leaving only the one between Customer and Car.

Other Areas Affected by Relationships

There are other areas of Inspector that are affected by the relationships Inspector is able to recognize. These include selecting data members for

Editing Data Members

This section describes how to edit data members using the Edit Data Member dialog box.

Use Care When Editing Data Members

When you edit a data member, you are editing a value in an ObjectStore database. Be sure that you are aware of all the effects changing a data member might have on your database and the applications that use it.

Example

Consider editing an instance of type char*. If you edit this instance using the Edit Data Member dialog box, you need to decide whether to

Create a new block for the edited instance and retain the existing block
Create a new block for the edited instance and delete the existing block
Use the existing block

Making any of these choices might cause side effects that Inspector cannot predict. Alternatively, you could use manage this behavior using user-defined methods.

For more information: See Chapter 7, User-Defined Methods to learn more about user-defined methods.

Using the Edit Data Member Dialog Box

The Edit Data Member dialog box has a number of features that allow you to edit several types of instances.

The Editable Data Members list box appears on the left side of the dialog box. It displays all the editable data members of the instance you have selected from the database.

Tip: Once you edit a data member value, the data member type and name appear in italics.

The right side of the dialog box, which is initially empty, displays different tools based on the data member you select.

The Member Variable Value field displays the data member's current value. Different display options are available for different data member types. For example, you can display a char* type data member using either its literal value, or hexadecimal notation alongside the literal value. Inspector displays a list of valid values for data members with an enumerated type.
The >> button expands the dialog box to display other information, such as extent values for ObjectStore relationships. Once you have extended the dialog box, the >> button changes to <<, which enables you to restore the dialog box to its original dimensions.

How to open the Edit Data Member dialog box

To open the Edit Data Member dialog box:

Select the instance you want to edit.
Click Instance | Edit on the menu bar, or select Edit from the instance shortcut menu.

How to Edit a Data Member

Prerequisite

In order to edit a data member, you must have write access to the ObjectStore database in which the instance to which it belongs is stored. If you have navigated to an instance in a database other than the one you opened in Inspector, your ability to write to that database is controlled by the Open Databases in MVCC to Resolve External References field on the Instances page of the Options dialog box.

This option is selected by default, which means that you will not have the write access required to edit navigated instances.

For more information: See Inspector Options to learn how to set options.

Changing your mind

Inspector provides several ways for you to undo edits to data members before committing them to ObjectStore. You should be familiar with these methods before editing a data member value.

Original Values button - The Original Values button appears beneath the edit field on the Edit Data Member dialog box once you have changed a data member's value. Click this button to undo the current edit.
Cancel button - The Cancel button on the Edit Data Member dialog box undoes the current edit and closes the dialog box.
Confirmation dialog box - If you click OK on the Edit Data Member dialog box, Inspector displays a confirmation message. Click No if you change your mind about the edit to the current data member but want to review other changes.
Click Cancel to return to the Edit Data Member dialog box. Note: Clicking Cancel does not restore edited data members to their original values.

Data member editing procedure

The basic procedure for editing data members using the Edit Data Member dialog box is shown here. Information specific to editing different types is provided following the procedure.

To edit a data member:

Select the instance containing the data member you want to edit.
Open the Edit Data Member dialog box.
Select the data member whose value you want to edit from the Editable Data Members list box.

The contents of the dialog box change based on the type of the data member you selected.
Make the edits you require.

The Original Value button appears beneath the edit field.
Click OK to complete the change.

Inspector displays a dialog box asking you to confirm the edit.
Click Yes to review each edit independently.

Click Yes to All if you want Inspector to accept all edits without any additional confirmation.

Recommendations for Editing Specific Types

char and char*

You can edit character strings (type char) and pointers (type char*) using either the literal value or the hexadecimal value.

If you choose to edit the hexadecimal value, make sure that the string terminates with 00 (null). If you do not terminate the string with the null character, Inspector interprets the data member type as blob.

Enumerated types

When you edit an enumerated type, you choose from a list of valid values in the Member Variable Value field. For example, for a type of EnumSize, the Member Variable Value field might display a list containing small, medium, and large.

Memory and pointers to memory

When you edit a data member variable that is either a block of memory or a pointer to memory, you can change the hexadecimal value.

You have three choices regarding the block of memory itself.

Memory Block Option When to Use
Make the changes in a new block and delete the existing one

When the block of memory containing the instance you are editing is used only by that instance

Make the changes in a new block and retain the old one

When the block of memory containing the instance you are editing is used by other instances

Make changes in the existing block

When the new value is the same size as or smaller than the existing value. Note that you cannot add new bytes to the end of the block

Memory Block Option	When to Use
Make the changes in a new block and delete the existing one	When the block of memory containing the instance you are editing is used only by that instance
Make the changes in a new block and retain the old one	When the block of memory containing the instance you are editing is used by other instances
Make changes in the existing block	When the new value is the same size as or smaller than the existing value. Note that you cannot add new bytes to the end of the block

Note that new blocks of memory are always created in the default segment.

Relationships

You edit relationships by adding instances to or removing instances from the relationship as shown in the Member Variable Value list box.

Tip: The <=> symbol identifies relationships in the Editable Data Members list box.

If you click the expand button (>>), the Edit Data Member dialog box displays the extent of the class related to the class whose instance you are editing in the Extent of Class list box. (If this list box is empty, it means either that the extent is empty or that Inspector does not know where to locate the extent.) You use the right arrow button to remove instances from the relationship; you use the left arrow button to add instances to the relationship.

Note that Inspector maintains referential integrity for ObjectStore relationships. For example, consider a Triumph vehicle instance associated with (owned by) a Smith customer instance. If you edit the Triumph instance and associate it with, say, Homer, that Triumph is no longer owned by Smith once you confirm the edit.

C++ pointers and C++ references

You edit pointers in the same way you edit relationships: by adding and removing instances. Remember, to display instances, click the expand (>>) button.

Tip: The => symbol identifies pointers in the Editable Data Members list box.

To make a pointer point to an instance:

Select the instance from the Extent of Class list box.
Click the left arrow to place the instance in the Member Variable Value entry field.
Click the OK button.

To set a pointer to NULL:

Select the instance in the Member Variable Value entry field.
Click the right arrow to remove the instance.
Click the OK button.

Interpreting and Displaying Strings

Overview

C++ enables you to encode strings in several formats, the most common of which is ASCII. The String Formats page of the Options dialog box contains options that

Help Inspector interpret strings
Let you control how strings are displayed
Let you control how single characters are displayed

You can use these options to make the information you see in Inspector consistent with its native format, that is, the format in which you are familiar with it.

For more information: To learn more about options and how to set them, see Inspector Options.

When Are Interpretation and Display Rules Used?

By default, Inspector interprets (and displays) any string with more than 768 characters as an ASCII blob. Instances that are interpreted as blobs are displayed using a hexadecimal viewer.

Strings with fewer than 768 characters are interpreted and displayed based on the rules you select.

Interpreting Strings

By default, Inspector interprets strings using plain ASCII. You use the options in the Interpret Strings As group box to

Specify a different standard
Provide other information to help Inspector interpret strings

ASCII alternatives

You can use the Default Encoding Type drop-down list to select an alternative to plain ASCII:

SJIS - the standard Japanese double-byte character string for Windows Note that there is a separate option to help Inspector interpret Japanese strings coded using formats other than SJIS.
JIS - Japanese double-byte character strings for UNIX
EUC - the standard UNIX double-byte character string
UTF-8 - Unicode for Java
Unicode little endian - Unicode in little endian format
Unicode big endian - Unicode in big endian format
Automatically Recognize SJIS, JIS, or EUC - inspector decides how to interpret strings

Interpreting unsigned arrays

By default, unsigned arrays are interpreted as Unicode encoded strings in little endian format; big endian format is also supported. If the Automatically Recognize SJIS, JIS, or EUC field is not checked, unsigned arrays are displayed as arrays of numbers.

Displaying Strings

The options in the Show Strings group box let you define

How long a string must be before it is considered a blob
How to display strings

When is a string a blob?

By default, a string is interpreted as a blob if it exceeds 768 characters.

Display options

If a string is not interpreted as a blob, you can display the string

Up to the first NULL character (assumes the C++ standard of 0 for the NULL character)
Skipping invalid characters; invalid characters are not included in the display
Substituting a special character for invalid characters; the default special character is a question mark (?)

If the string is interpreted as a blob, you can choose to display the string in ASCII, up to the first NULL character; remaining characters are truncated.

Displaying Single Characters

By default, Inspector displays single characters along with their ASCII values. For example, the letter D is shown as `D' (68). If you want, you can display single characters by themselves.

Overriding Inspector Defaults

You can override default settings for individual data members using the Data Member String Format dialog box.

The settings on this dialog box are the same as those on the String Formats page of the Options dialog box.

How to display the Data Member String Format dialog box

To display the Data Member String Format dialog box:

Display a database view.
Select the schema pane.

Note: You cannot use the tree hierarchy format for this procedure.
Click Schema | Data Member String Format on the menu bar.

Alternative: Click Set Attribute Format on the diagram content menu.
The Data Member String Format dialog box appears.