PreviousDebugging Object COBOL Applications Compiling and Shipping OO ApplicationsNext"

Chapter 24: Using the Object Inspector (Windows NT & OS/2)

This chapter describes the Object Inspector, an additional Animator V2 function which makes debugging Object COBOL programs easier. This function is only available on 32-bit Object COBOL on Windows and OS/2 systems.

24.1 Overview

Many of the data items in an Object COBOL program are object handles, held in data items declared as OBJECT REFERENCE. An object handle enables the run-time system to locate an object so that you can send it a message.

The Object Inspector extends the Examine function in Animator V2 so that when you query an object reference data item, you can see its class and whether it is a class or an instance. You can also see and change the values of the object's data (only the data declared in the Object-Storage Section).

If an object's data includes handles to other objects, you can also examine those to see the information they contain.

24.2 Using the Object Inspector

The Object Inspector starts whenever you Examine a data item which has been declared as OBJECT REFERENCE. The Examine function is documented fully in the chapter Executing Your Applications with Animator V2 in the Object COBOL User Guide, but briefly, there are three ways to examine a data item:

All of these methods will start the Object Inspector if the data item you attempt to examine has been declared as OBJECT REFERENCE. This includes all class-names declared in the Class-Control paragraph, and the reserved words SELF and SELFCLASS. The Object Inspector displays three kinds of information about the selected object:

>>To inspect an object

The title bar contains the name of the OBJECT REFERENCE data item you examined. The line below shows the object description.

The main areas in the window are as follows:

Title bar Shows the name of the data item you examined. If the class of this object has not been compiled for animation (no .idy file), it also displays the text "no .idy file" in parentheses.
Description line The text returned by the "description" method. If the object does not have its own "description" method, the default method in Base displays the class of the object and whether or not it is an instance.

If you try to examine a class-name before the run-time system has loaded the class, the description line displays "Class not loaded".

Data area Shows the object's attributes (the data declared in the object-storage section). The first line is always SELF, which represents the handle for the object. See below for a full explanation of the data area.
Push buttons Enables you to change the type of information shown by the Object Inspector window. The default is to show you the data-name and its COBOL picture.

Figure 24-1: Object Inspector Window

The data area displays SELF, and the lines below show the inheritance hierarchy of this object. If there is an .idy file for the object's class, the data area also shows the attributes of the object. Data items are shown in upper-case, and superclass names in lower-case.

A plus sign (+) next to a superclass indicates that data is inherited from the superclass, but not displayed (this is the default). A minus sign (-) next to a superclass indicates that either no data is inherited from this superclass, or that the data is already displayed.

>>To display inherited data

The sign changes from a plus to a minus, and the inherited data is displayed below the class-name (see Figure 24-2).

Figure 24-2: Displaying Inherited Data

>>To hide inherited data

The default display in the Object Inspector shows you the data-name and picture of the object data. You can change this to show the data-name and data values, or to show the data-name, picture and the data.

>>To display the data values

>>To display the data values and the picture

>>To display the picture only

You can also change the values of an object's attributes using the Object Inspector, provided that you have an .idy file for the object's class.

>>To change object attributes

If the data item is not an Object Reference, this opens an Animator V2 Examine Report window (see Figure 24-5). You can edit the data in text if the data item is a literal, or in hex otherwise. Pushing the Text/Hex button switches the window display between hexadecimal and text.Push the Apply button or press the Enter key to enter your changes into the data item. Press the Escape key to cancel your changes.

Figure 24-5: Animator V2 Examine Report window

If the data item is an object reference, this opens another Object Inspector window. You can use the new window to examine and modify the data in the object.

Object Inspector windows stay open until you close them, or shut down Animator V2.

>>To close an Object Inspector window

24.2.1 Inspecting Class Library Objects

Where there is no .idy file for a class, the Object Inspector can only show you a description of any objects of that class; it can't show the object attributes. Classes from the Class Library are not supplied with .idy files, but since you have all the sources, you can create your own, by compiling classes of interest for animation. The Object Inspector only needs the .idy file; the class executable can remain in native code form.

>>To compile a class for use with the Object Inspector

  1. Compile the class with the NOGNT directive.

    The Compiler creates a .int and .idy file. You can delete the .int file unless you are going to animate the class (see the section Animating the Class Library in the chapter Introduction to the Class Library for more information).

  2. Either copy the .idy file to the current directory from which you are animating your application, or set the COBIDY environment variable to point to the directory containing the .idy file.

The sources for the Object COBOL Class Library are installed by default into \cobol\source\oops on the drive containing your Object COBOL system.

24.2.2 Writing the "description" Method

If you are designing a class library for others to use, you might want to include a "description" method in your classes. This will help anyone debugging an application which uses your classes if they do not have access to your source or .idy files.

Implement the interface to "description" as follows:

 method-id. "description".
 linkage section.
 01 lnkString            object reference. 

 procedure division returning lnkString.
* Code to return a string describing the object. 
 exit program.

 end method "description".

The object returned must be either a COBOLPICX or a CharacterArray instance, of no more than 77 characters in length. Any data beyond 77 characters is ignored.

You can get the class name of an instance object by sending the message "className" to self. To get the name of a class object, send the message "name" to self. Both these methods are documented in the on-line Class Library Reference under the Base class.

Note: If you inspect an object which has a "description" method, when the object is in .int code format, you will see Animator V2 execution switch to the "description" method. You will have to step through the execution code, before the Object Inspector window appears and before Animator V2 execution returns to the point before you started inspecting the object.

24.3 Limitations

The Object Inspector has the following limitations:

Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousDebugging Object COBOL Applications Compiling and Shipping OO ApplicationsNext"