OS/2 Shareware BBS: 10 Tools/10-Tools.zip/cset21v1.zip/IBMCPP/HELP/DDE4BTUT.INF

OS/2 Help File | 1993-10-01 | 131KB | 1,140 lines

ΓòÉΓòÉΓòÉ 1. Special Notices ΓòÉΓòÉΓòÉ

References in this help to IBM products, programs, or services do not imply
that IBM intends to make these available in all countries in which IBM
operates.

Any reference to an IBM licensed program in this help is not intended to state
or imply that only IBM's licensed program may be used.  Any functionally
equivalent product, program, or service that does not infringe on any of IBM's
intellectual property rights may be used instead of the IBM product, program,
or service.

Evaluation and verification of operation in conjunction with other products,
except those expressly designated by IBM, is the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in
this tutorial.  The furnishing of this tutorial does not give you any license
to these patents.

This tutorial may contain examples of data and reports used in daily business
operations.  To illustrate them as completely as possible, the examples may
include names of individuals, companies, brands, and products.  All of these
names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.

The following terms, denoted by an asterisk (*) in this tutorial, are
trademarks of the IBM corporation in the United States and/or other countries:

 C Set ++
 IBM
 OS/2
 Operating System/2
 Presentation Manager
 WorkFrame/2


ΓòÉΓòÉΓòÉ 2. Start Here ΓòÉΓòÉΓòÉ

Welcome to the IBM* C/C++ Tools Browser Tutorial.  This tutorial gets you
started with the main features of the browser by guiding you through a sample
program provided with the C/C++ Tools compiler.

You will interact directly with the browser while viewing this tutorial. You
may want to work through the tutorial using the sample program, or just read
the tutorial to learn the main features of the browser, and then compile and
study one of your own programs.  You can also print the tutorial.

It is recommended that you work through each lesson in the order that they are
presented.  Each lesson builds on the knowledge gained from the previous
lessons.

This tutorial takes about an hour to complete.  You can stop anytime by
pressing F3 or selecting Exit from the Services pull-down menu of the tutorial
window.  To continue, click on the Forward push button.


ΓòÉΓòÉΓòÉ <hidden> Printing the Tutorial ΓòÉΓòÉΓòÉ

You can print this tutorial if you want to follow it on paper.  To print the
tutorial:

 1. Click on the Print push button at the bottom of this window. The Print
    window appears.

 2. Select the All Sections radio button to print the entire tutorial.

Click on the Back push button to return to the previous panel and continue
viewing the tutorial.


ΓòÉΓòÉΓòÉ 2.1. Getting Help ΓòÉΓòÉΓòÉ


This tutorial guides you through the basic functions of the C/C++ Tools browser
by allowing you to interact directly with it.

Contextual online help is available throughout the browser for each menu
option, field, and push button.  You can get help from the Help pull-down, the
Help push button (where present), or by pressing F1 while highlighting the
particular item you want help with.


ΓòÉΓòÉΓòÉ 2.2. What is a Browser? ΓòÉΓòÉΓòÉ

A browser is a programming tool that you can use to examine your program in
many different ways.

Using a browser, you can scan a list of program components, view your source
code, and look at an inheritance graph for a particular base class.  Instead of
working through the passive declarations in your source code to determine
program structure, you can look at a graph that visually illustrates the
relationships that exist between your program components.

The C/C++ Tools browser helps you study programs developed in IBM* 32-bit C++.


ΓòÉΓòÉΓòÉ 2.3. The Browser User Interface ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ

The C/C++ Tools browser interface consists of four window types.  Double-click
on a window type below to learn more about it:

o Browser Control window

o List window

o Graph window

o Text window

Note:  Before you click on the Forward pushbutton, double-click on the name of
       each window type in the list above.


ΓòÉΓòÉΓòÉ <hidden> Browser Control Window ΓòÉΓòÉΓòÉ

The Browser Control window is the starting point for program examination using
the browser.  All open browser windows are accessible from this window.
Operations that affect the entire browser are also performed here.


ΓòÉΓòÉΓòÉ <hidden> List Window ΓòÉΓòÉΓòÉ

A List window lists program components alphabetically, by name. Through
database searches and queries, you can specify filters so that only the program
components you want to examine are displayed on the screen.


ΓòÉΓòÉΓòÉ <hidden> Graph Window ΓòÉΓòÉΓòÉ

A Graph window shows the relationships between program components by drawing
nodes that represent program components, and lines between nodes to illustrate
their relationships.


ΓòÉΓòÉΓòÉ <hidden> Text Window ΓòÉΓòÉΓòÉ

A Text window allows you to view and edit the source code associated with a
particular program component.


ΓòÉΓòÉΓòÉ 2.4. Browsing the Database ΓòÉΓòÉΓòÉ

The browser database contains all the information about the program components
you want to examine.  You can create different views of the browser database by
performing searches and queries from List, Graph, and Text windows opened from
the Browser Control window.


ΓòÉΓòÉΓòÉ 2.5. About the Sample Program ΓòÉΓòÉΓòÉ

The sample program for this tutorial is a C++ payroll program called
PAYROLL.CPP. It produces a monthly pay summary of a company based on the salary
and commissions paid to employees.  Employee categories include managers, sales
managers, sales persons, and regular employees.  Each employee category is
defined as a class derived from a base class called employee.

In this tutorial, you use the browser to list the program components in a List
window, examine the employee class hierarchy in a Graph window, and examine the
source code for the program in the Text window.

Click the on the Forward push button to view Lesson1: Compiling the Sample
Program.


ΓòÉΓòÉΓòÉ 3. Lesson 1: Compiling the Sample Program ΓòÉΓòÉΓòÉ

To use the browser, you first need to compile your program using the /Fb
option.  If you want to try compiling the sample program PAYROLL.CPP now, open
an OS/2* prompt and change to the c:\ibmcpp\samples\browser directory.  Then,
type the following from the OS/2* prompt, and press Enter:

icc /Fb payroll.cpp

Note:  If you installed the IBM* C/C++ Tools product in a directory other than
       c:\ibmcpp, it is imperative that you perform this step to update the
       sample browser file on the location of the program source files.
       Substitute your directory name when typing the commands.

You may also use any of the other compiler options but you must use the /Fb
option.  It instructs the compiler to generate the necessary browser files you
will need to examine the program source code using the browser. The generated
browser files have the same name as the main source file of the program, with a
.BRS file name extension.

So that the browser can use the information in the .BRS files, you must load
them into the browser database.  Loading browser files is discussed in Lesson
2: Using the Browser Control Window.


ΓòÉΓòÉΓòÉ 3.1. Starting the Browser ΓòÉΓòÉΓòÉ

If you haven't started the browser yet, now would be a good time to do so.  You
can start the browser from an OS/2* command prompt, or from the Desktop.

To start the browser from your Desktop:

 1. Open the IBM C/C++ Tools 2.0 folder on your Desktop. The IBM C/C++ Tools
    2.0 - Icon View folder appears.

 2. Double-click on the C++ Browser icon in the folder.

To start the browser from an OS/2 command prompt:

 1. Open an OS/2 window or full screen command prompt.

 2. At the command prompt, type ibrs .

For more information on how to start the browser, and how to use the browser
command-line options, refer to the browser on-line help or the Browser
Introduction booklet.


ΓòÉΓòÉΓòÉ 3.2. What You Have Learned ΓòÉΓòÉΓòÉ

You have completed Lesson 1: Compiling the Sample Program. You have learned how
to:

o Compile a program with the /Fb option to generate a browser file.

o Start the browser from the Desktop or from an OS/2* command prompt.

Click on the Forward pushbutton to continue to the next lesson, Lesson 2: Using
the Browser Control Window.


ΓòÉΓòÉΓòÉ 4. Lesson 2: Using the Browser Control Window ΓòÉΓòÉΓòÉ

The browser opens with the Browser Control window and three minimized browser
windows.  If you started the browser without specifying input browser files on
the command line, the Load Browser File action window displays automatically.
For now, select the Cancel pushbutton to remove the Load window from the
screen.

The Browser Control window serves as the control area of the browser and is
displayed during the entire browser session.  You invoke operations that apply
to the entire browser session from this window.


ΓòÉΓòÉΓòÉ 4.1. Browser Window Icons ΓòÉΓòÉΓòÉ

The client area of the browser Browser Control window contains icons that
represent the open windows in the current browser session.
The icon that looks like this represents an open list window.  The number 1 in
the icon title List:1 means that the icon represents the first list window
opened in the current browser session.

Likewise, this icon and this icon represent the first Graph and Text windows
opened in the current browser session.

The icons remain displayed in the Browser Control window until their
corresponding windows are closed.


ΓòÉΓòÉΓòÉ 4.2. Loading a Browser File ΓòÉΓòÉΓòÉ

To examine the components of a program using the browser, you must first load
the browser .BRS file associated with the program into the browser database.

You can load and unload as many browser files as you need from the Control
window.  Once you load a browser file, all program elements associated with it
become accessible from any List, Graph, or Text window.
Browser windows display program components from all the loaded browser files
together.  This means that you can have a project divided into many parts that
are developed and compiled separately, and still be able to examine the project
as a whole by loading all the applicable browser files into the browser
database.


ΓòÉΓòÉΓòÉ 4.3. Reduce the Tutorial Window ΓòÉΓòÉΓòÉ

So that you can more easily work with the Browser Control window and view the
rest of this tutorial at the same time, reduce this tutorial window to a
convenient size and then move it to the side of the screen.

You may also want to size browser windows as you work with them so that the
tutorial window and your working browser window are arranged side by side on
the screen.

To view the table of contents again, click on the Contents pushbutton.


ΓòÉΓòÉΓòÉ 4.4. Loading the Sample Browser File ΓòÉΓòÉΓòÉ

Now, load the browser file for the sample program PAYROLL.CPP:

 1. From the Database pull-down in the Browser Control window, select Load.
    The Load Browser File window appears.

 2. Click on the down arrow to the right of the Drive field to display all the
    drives in your system.  Select the drive that contains the installed IBM*
    C/C++ Tools product.

 3. From the  Directory list, select the IBMCPP directory (if you installed the
    C/C++ Tools product in another directory, substitute its name here).  Next,
    select the SAMPLES subdirectory, then the BROWSER subdirectory.

 4. Select PAYROLL.BRS from the File list box.

 5. Click on the Load push button to load the PAYROLL.BRS file.

After a few seconds, the PAYROLL.BRS file is loaded into the browser database,
and all its components are accessible from any browser window.


ΓòÉΓòÉΓòÉ 4.5. Opening Browser Windows ΓòÉΓòÉΓòÉ

You can open a new List, Graph, or Text window from the Browser Control window,
or you can double-click on a browser window icon to restore a browser window
that has already been opened.

     Try opening a new List window by selecting the Database menu bar option,
     and then selecting Open  List.

 An empty List window should appear together with an icon in the Browser
 Control window labeled List:2.  It represents the second List window opened in
 the current browser session.

     Return to the Browser Control window and try double-clicking on the Graph
     window icon to restore the Graph window.

 Note that browser windows are empty when you first open them.  Because you
 must perform a search or query to fill the window with program components, the
 Search Database action window appears  automatically if you have not yet
 performed an object query or copied an object into the object list. For now,
 select the Cancel pushbutton to remove the Search Database window from the
 screen. You'll find out about searches and queries in the next lesson, Using
 the List Window.


ΓòÉΓòÉΓòÉ 4.6. What You Have Learned ΓòÉΓòÉΓòÉ

You have completed Lesson 2: Using the Browser Control Window. You have learned
how to:

 o Load browser .BRS files into the browser database

 o Open new List, Graph, and Text windows

 o Restore opened browser windows by double-clicking on their corresponding
   icons in the Browser Control window.

 Now minimize any open Graph, List, or Text windows, and then continue to
 Lesson 3: Using the List Window.


ΓòÉΓòÉΓòÉ 5. Lesson 3: Using the List Window ΓòÉΓòÉΓòÉ

Return to the Browser Control window and make a List window active by
double-clicking on its icon.

You use the List window to generate lists of elements from the browser database
that meet the selection criteria you specify when you do a database search or
object query.


ΓòÉΓòÉΓòÉ 5.1. Introduction to Database Searching ΓòÉΓòÉΓòÉ

The first step in examining program components is to perform a database search
or object query. Searches and queries can be refined by specifying filters that
limit the search or query to the set of program components you want to
investigate.  You can specify Scope, Category, and Attribute filters in a
Search Database or Query Object window.

This is what a Search Database window looks like:


ΓòÉΓòÉΓòÉ 5.2. A Search for All Database Objects ΓòÉΓòÉΓòÉ

Now, perform a database search that lists all the objects in the browser
database:

  1. If the Search Database window is not already displayed, select Browse from
     the List window menu bar and then select Search Database from the Browse
     pull-down.

     Note that each filter in the Search Database window has a default value
     associated with it.  For the Scope filter, the default is All Names.

  2. Click on the Category push button and then select No Filter from the
     adjacent list box.  Leave the default value No Filter for the Attribute
     filter.

     The filter values you have just specified open the search to all the
     objects in the browser database.

  3. Click on the Search push button to start the database search.

 After a few seconds, all the objects in the browser database are displayed in
 the List window.


ΓòÉΓòÉΓòÉ 5.3. List Window Qualifiers ΓòÉΓòÉΓòÉ

The Kind option in the View pull-down of the List window lets you see the kind
of each object in the list.

     From the View pull-down in the List window, select Kind. The kind of each
     object is now displayed after each object name, preceded by a dash (-).

 The Qualification option in the View pull-down displays additional information
 about each element in the list, such as its access specifier, path, or type.
 For example, class members are always qualified by the name of their class,
 and functions are qualified by their arguments and return type.

 Because the Qualification option is active by default, all the object names
 that are displayed in the list window at the moment are qualified names. Turn
 Qualification off to see what the object names look like without
 qualification:

  1. From the View pull-down, select Qualification to turn off qualification.
  2. After looking at the unqualified names, turn Qualification on by selecting
     it from the View pull-down again.  A check mark appears beside your
     selection when Qualification is on.

 Qualifiers are most useful for sorting.  When the Kind or Qualification
 options are active, the Sort function in the View pull-down on the List window
 sorts the list items on their fully qualified names.  This means that you can
 sort on type, path, and other information when qualification is turned on.


ΓòÉΓòÉΓòÉ 5.4. Searching for All Classes ΓòÉΓòÉΓòÉ

You have just performed a database search to list all the objects in the
browser database. You could have performed a more selective search by
specifying Category and Attribute filters to include only the objects you want
to examine.

For example, to perform a database search that lists all the classes in the
database:

  1. From the Browse pull-down, select Search Database  The Search Database
     window appears.

  2. Since a search for all classes is the default for a list window search,
     the Scope, Category, and Attribute filters already have the following
     values:

    Scope       All Names
    Category    Class
    Attribute   No Filter

     In this case, the search is not  limited to a particular attribute of a
     class, such as Roots, which would limit the search to only the root
     classes in the database.

  3. Click on the Search push button to start the search.

 The list of all the classes in the PAYROLL.CPP program is displayed in the
 List window.


ΓòÉΓòÉΓòÉ 5.5. Copying into the Object List ΓòÉΓòÉΓòÉ

The browser provides an Object List that holds the names of objects that can be
queried from any browser window.  For example, if you have the employee class
displayed in the List window, you can copy it into the Object List from the
List window then invoke a query from the Graph window to look at its
inheritance graph.

Objects in the Object List are shared between browser windows.


ΓòÉΓòÉΓòÉ 5.6. Example: Copying into the Object List ΓòÉΓòÉΓòÉ

Now, try copying the sales_mgr class into the Object List:

  1. Move to the top of the list using the scroll bars or by pressing the Home
     key.

  2. Move to the sales_mgr entry by pressing s. (To quickly move to an item or
     group of items whose names begin with a certain letter, simply type the
     letter.)

  3. From the Browse pull-down, select Copy to Object List. The sales_mgr class
     is now copied into the list.

 There is now one object in the Object List.  Repeat the above steps and copy a
 few more objects into the Object List.

 You will use the Object List in forthcoming lessons on the Graph and Text
 windows.


ΓòÉΓòÉΓòÉ 5.7. Introduction to Object Querying ΓòÉΓòÉΓòÉ

Now that you have the list of all the classes in the PAYROLL.CPP program
displayed in the List window, you can see more information about a specific
class in the list. For example, you can generate a list of all the member
functions of the employee class using the Query Object action. The filters that
you specify for a query apply directly to the object being queried. Here is
what the Query Object window looks like:

The only difference between a Search Database window and an Query Object window
is the additional entry field called Objects in the Query Object window. It
contains the name of the object being queried.  When you query a selected
object, the object is automatically copied into the Object List.  To see the
objects in the Object List, you click on the down arrow on the right side of
the Objects entry field.


ΓòÉΓòÉΓòÉ 5.8. A Query Example ΓòÉΓòÉΓòÉ

Now, try a query on the employee class that lists all its member functions:

  1. Select the employee class from the list; it should be the first item.

  2. From the Browse pull-down, select Query Object to bring up the Query
     Object window

  3. Click on the down arrow on the right side of the Objects entry field to
     see the entries in the object list.  Select employee - class from the
     list.

  4. Leave the default filter value Members for the Scope filter.  Using this
     filter, you are refining the search to all the members of the query object
     employee.

  5. Click on the Category push button and then select Function from the list
     box.  By selecting Function for the Category filter, you are further
     limiting the query to all the members of the employee class that are
     functions.

  6. Leave the default filter value No Filter for the Attribute filter.

  7. Click on the Query push button to start the query.

 You see a list of all the member functions of the class employee on the
 window.


ΓòÉΓòÉΓòÉ 5.9. Looking at Status Bars ΓòÉΓòÉΓòÉ

You can see the parameters of your last search or query on the Object and Query
status bars that appear near the top of the browser windows. The Size status
bar shows the number of objects there are in the displayed list.

You can control which status bars you want displayed or hidden for the current
window by using the Status option in the View pull-down. For example, to hide
the Size status bar:

     Select Status  Size from the View pull-down. The check mark beside it
     disappears and the Size disappears from the list window screen.

 The Status function works the same way in other browser windows.


ΓòÉΓòÉΓòÉ 5.10. What You Have Learned ΓòÉΓòÉΓòÉ

You have now completed Lesson 3: Using the List Window.  You have learned how
to:

 o Use Search Database to specify Scope, Category, and Attribute filters for a
   database search.

 o Use the List window object qualifiers Kind and Qualification

 o Use Copy to Object List to copy objects into the Object List

 o Use Query Object to query a selected object or an object in the Object List

 o Use the Status option to hide and display status bars.

 Minimize the List window and then continue to Lesson 4: Using the Graph
 Window.


ΓòÉΓòÉΓòÉ 6. Lesson 4: Using the Graph Window ΓòÉΓòÉΓòÉ

Now, return to the Browser Control window and make a Graph window active by
selecting its icon.

The Graph window is used to graphically illustrate relationships between
program components.  The relationships are shown as nodes connected by lines.
Using the Graph window, you can quickly determine program complexity and
dependencies by looking at the number of nodes in the graph and the
relationships between them.


ΓòÉΓòÉΓòÉ 6.1. Querying from the Graph Window ΓòÉΓòÉΓòÉ

Some of the graphs that you can generate from the Graph window are:

 o Inheritance graph
 o Directory tree
 o Program structure
 o File inclusion tree
 o Function call map

 Because the employee class was copied into the Object List from the List
 window when you performed a query on it, you can now query the employee class
 from the Graph window to display a graph that shows its relationship with its
 derived classes.


ΓòÉΓòÉΓòÉ 6.2. A Graph Query Example ΓòÉΓòÉΓòÉ

Now, perform a Derived Classes query on employee:

  1. From the Browse pull-down in the Graph window, select Query Object.

  2. Select employee - class from the Objects dropdown list in the Query Object
     window.

  3. Select Derived Classes from the list box for the Scope filter.

  4. Leave the default filter value Expand All for the Category filter to see
     all the descendants of employee.

  5. There are no Attribute filters for this query, so just click on the Query
     push button to start the query.

 You should see a graph showing all the derived classes of employee.


ΓòÉΓòÉΓòÉ 6.3. Another Graph Query Example ΓòÉΓòÉΓòÉ

Next, you can request all the base classes of sales_mgr (you can see from the
graph which classes these are).  This is the reverse of your last query.

  1. Tip: A quick way to Query a displayed object in any browser window is to
     double-click on it.  This action copies the selected object into the
     browser Object List and brings up the Query Object window with the
     selected item as the query object.

     Double-click on the sales_mgr node now.  The Query Object window appears
     with sales_mgr - class as the query object.

  2. Select Base Classes from the list box for the Scope filter.

  3. Leave the default filter value Expand All for the Category filter.

  4. Click on the Query push button to start the query.

 After a few seconds, a graph similar to the previous graph is displayed
 showing only the base classes of the sales_mgr class.


ΓòÉΓòÉΓòÉ 6.4. Searching from the Graph Window ΓòÉΓòÉΓòÉ

Next, you will perform a database search from the Graph window. This time you
will request for a larger graph showing a map of the function calls in the
PAYROLL.CPP program.

     Because this graph will be very large, set the graph drawing quality to
     Very High by selecting Quality  Very High from the View pull-down.

 This option produces a finer drawing of the graph by preventing overlapping of
 arcs, but takes a little longer to draw.

 To start the function calls query:

  1. From the Browse pull-down, select Search Database.

  2. In the Search Database window, select Calls from the list box for the
     Scope filter.

  3. Leave the default filter values Expand All and Called Functions for the
     Category and Attribute filters.

  4. Click on the Search push button to start the search.  This search could
     take a minute or two since this is a very large search action.

 Once the search is finished, a very large graph appears on the screen.  There
 are so many nodes that it is hard to see them all.  Fortunately, there is an
 easy way to scroll over the graph viewing only certain parts of it on the
 screen.


ΓòÉΓòÉΓòÉ 6.5. The Overview Window ΓòÉΓòÉΓòÉ

You can use the Overview window to quickly scroll and zoom over parts of the
graph to see it in more detail.

     From the View pull-down, select Overview.

 A small window that looks like the one shown here appears at the top right
 corner of the Graph window.  It contains a representation of the entire graph.

 The viewing rectangle that appears within the window represents the current
 view of the graph.  You can move and size the viewing rectangle to scroll over
 and display an enlarged or reduced portion of the graph.  The graph window
 changes to show the new position and size of the rectangle.


ΓòÉΓòÉΓòÉ 6.6. Using the Overview Window ΓòÉΓòÉΓòÉ

To size the viewing rectangle:

  1. Position the mouse pointer over a border of the rectangle.
  2. To see a reduced portion of the graph, press and hold mouse button 1 while
     dragging the border toward the center of the rectangle.  The rectangle
     contracts as you move the mouse.  When the rectangle is the size that you
     want, release mouse button 1.
  3. To see a enlarged portion of the graph, press and hold mouse button 1
     while dragging the border away from the center of the rectangle.  The
     rectangle expands as you move the mouse.

 To move the viewing rectangle:

  1. Position the mouse pointer anywhere within the rectangle.
  2. Press and hold mouse button 1 while moving the rectangle with the mouse.
  3. Position the rectangle over the set of nodes you want to view and then
     release mouse button 1.

 When the viewing rectangle is small enough, you can actually see the node
 labels of the graph in detail.  Move the viewing rectangle over the graph to
 view different parts of it.


ΓòÉΓòÉΓòÉ 6.7. Using the Zoom Slider ΓòÉΓòÉΓòÉ

Another way to enlarge or reduce the graph is to use the Zoom Slider.

Move the slider arm to the right to enlarge the graph, move it to the left to
reduce the graph.

Notice how the viewing rectangle in the overview window expands and contracts
to match your zoom actions.  The Zoom Slider also adjusts to your zoom settings
as you size the overview rectangle.

If a node is selected, the zoom action keeps the center focus on the selected
node as it redraws the graph.  If there is no selected node, the zoom action
focuses on the center of the graph.


ΓòÉΓòÉΓòÉ 6.8. Using Magnify ΓòÉΓòÉΓòÉ

You can also size a portion of the graph using the Magnify option from the View
pull-down.  There are two options in the cascaded Magnify menu:  Magnify  Area
In expands the selected rectangle to fit the Graph window display and Magnify 
Area Out shrinks the currently displayed view of the graph to fit into the
selected rectangle.

     Select Magnify  Area In or Magnify  Area Out. Notice that the mouse
     pointer changes to a magnification pointer.  This indicates that you can
     select a rectangular portion of the graph that you want reduced or
     enlarged.

 To select a portion of the graph to reduce or enlarge:

  1. Position the magnification pointer over the upper-left corner of the area
     you want to select.

  2. Press and hold mouse button 1 while sliding the mouse pointer diagonally
     over to the lower-right corner of the area you want to select.  The area
     you select is marked with a rectangle.

  3. When the rectangular marker is over the portion you want to select,
     release mouse button 1.  Notice what happens to the graph, the zoom slider
     and the overview window.  They are all updated to correspond with your
     Magnify action.


ΓòÉΓòÉΓòÉ 6.9. Collapsing Nodes ΓòÉΓòÉΓòÉ

If you have too many nodes on the screen and you want to remove some of them to
reduce the size of the graph, you can collapse a node to remove all its
descendants:

  1. Select a node in the graph with many levels of descendants.  The selected
     node is highlighted with a different color and has a thick border drawn
     around it.

  2. From the View pull-down, select Node  Collapse All.

 The descendant nodes and the arcs pointing to the children disappear. To make
 the dangling arcs visible, select Collapsed Arcs from the View pull-down.

 The collapsed node is differentiated from the expanded nodes by a rectangle
 drawn around it.  There may also be other nodes that were collapsed because
 they share hidden descendants with the node you chose to collapse.


ΓòÉΓòÉΓòÉ 6.10. Expanding Nodes ΓòÉΓòÉΓòÉ

To again see the invisible descendants of the collapsed node, you can expand
the node by a single level, or you can expand it entirely:

  1. Select the same node you collapsed before.

  2. From the View pull-down, select Node  Expand. Only the direct descendants
     of the collapsed node appear.

  3. Now, while the same node is still selected, select Node  Expand All from
     the View pull-down.

     Now all the direct and indirect descendants of the previously collapsed
     node are visible.


ΓòÉΓòÉΓòÉ 6.11. Centering on a Node ΓòÉΓòÉΓòÉ

To center the graph view on a particular node, select the node then select Node
 Center from the View pull-down.

The view of the graph adjusts so that the selected node is in the middle of the
screen.


ΓòÉΓòÉΓòÉ 6.12. Using Relay and Reset ΓòÉΓòÉΓòÉ

If you have scrolled and zoomed around the graph enough, you might want to see
the graph as it was originally drawn.  You can use the Relay action to do this.

     From the View menu, select Relay.  The graph is redrawn as it originally
     appeared when you first issued the query.

 To clear the graph window of its contents altogether, select Reset from the
 View pull-down.  You can try this now because you have just completed the
 lesson on using the graph window.


ΓòÉΓòÉΓòÉ 6.13. What You Have Learned ΓòÉΓòÉΓòÉ

You have now completed Lesson 4: Using the Graph Window. You have learned how
to:

 o Perform a Query Object action from the Graph window using objects copied
   into the Object List from other windows

 o Invoke a Query Object action on a displayed object by double-clicking on it

 o Perform a Search Database action from the Graph window

 o Use Quality to set the graph drawing quality.

 o Use the Overview window to scroll and zoom over the graph

 o Use the Zoom Slider to zoom in and out of the graph

 o Use Magnify to reduce or enlarge a specified portion of the graph

 o Use the Node actions Collapse All, Expand All, and Expand to display and
   hide descendants of nodes in the graph

 o Center a node in the graph using Node  Center

 o Redraw a graph using Relay

 o Clear the contents of the window using Reset.

 Minimize the active Graph window and then continue to Lesson 5: Using the Text
 Window.


ΓòÉΓòÉΓòÉ 7. Lesson 5: Using the Text Window ΓòÉΓòÉΓòÉ

Now, return to the Browser Control window and make a Text window active by
selecting its icon.

You can use the Text window to display the actual source code associated with a
particular object in the database.  You can even edit the source information;
however, any changes that you make will not be reflected in the browser
database until you recompile your program and reload the appropriate browser
files into the browser database.


ΓòÉΓòÉΓòÉ 7.1. What are Occurrences? ΓòÉΓòÉΓòÉ

The result of a search or query in a Text window is a list of occurrences.  An
occurrence may be a source-code file or an instance of a browser object in a
source file, depending on the performed action.


 When the    The occurrences list
 action      is...
 is a...
 ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
 Database    A list of all the
 search      source-code files in
             the database.
 ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
 Object      A list of instances
 query       where the query object
             appears in one or more
             source files in the
             database.


ΓòÉΓòÉΓòÉ 7.2. Searching in the Text window ΓòÉΓòÉΓòÉ

A search action from a Text window is a request for all the source files in the
database.  To start a search:

  1. From the Browse pull-down, select Search Database to bring up the Search
     Database window.

  2. Click on the Search push button to start the search.

 The first source file in the occurrences list is displayed in the window, and
 the number of occurrences found is displayed on the status bar.

     To look at the list of occurrences, select Occurrences  List from the
     Text pull-down.  The Occurrences List window appears. You can select a
     file to view from the occurrences list by selecting it then clicking on
     the Display push button.

 You can also use the Occurrences  Next (F12) and Occurrences  Previous (F11)
 controls to rotate through the sequence of occurrences.  If the Occurrences
 status bar is displayed, you can click on the ring icons on the top right-hand
 corner of the status bar to rotate through the list of occurrences.


ΓòÉΓòÉΓòÉ 7.3. The Occurrence Status Bar ΓòÉΓòÉΓòÉ

The Occurrence status bar displays the name of the occurrence currently being
viewed.

Other status bars are Object and Query which display the parameters of your
last database search or object query, and Size which displays the number of
lines in the currently displayed file.


ΓòÉΓòÉΓòÉ 7.4. Copying into the Object List ΓòÉΓòÉΓòÉ

In the Text window, copying an object into the Object List is as simple as
selecting its name from the text, and then selecting Copy to Object List from
the Browse menu.  To copy an item into the Object List:

  1. Display the PAYCLASS.H file by selecting its name from the Occurrences
     list.

  2. Search for the regular_emp class using the Find action:

     a. From the Edit pull-down, select Find. The Find window appears.
     b. Type regular_emp in the Find entry field.
     c. Click on the Find push button to start the search.

     The first occurrence of the string regular_emp is highlighted in a comment
     in the text.

  3. From the Edit pull-down, select Find Next to locate the next occurrence in
     the list.  Now the string regular_emp is highlighted in a class
     declaration.

  4. Select Copy to Object List from the Browse menu to copy the class into the
     object list.

 Note:  You could also have highlighted the text by marking it with the mouse
        or keyboard to copy it into the Object List, instead of using the Find
        action to find and highlight the text.


ΓòÉΓòÉΓòÉ 7.5. Tips for Copying into the Object List ΓòÉΓòÉΓòÉ

Here are a few things to remember when you are selecting objects to copy into
the Object List from the Text window:

 o The selected object must be a valid name in the browser database

 o Select the name of an object only in a valid portion of the source code.  Do
   not select the name of an object in a comment, for example, because the
   selection loses its proper context and cannot be interpreted.

 o Do not select more than one name at a time.  When more than one object is
   selected, only the first object is copied. Sometimes, nothing is copied at
   all.


ΓòÉΓòÉΓòÉ 7.6. Querying in the Text Window ΓòÉΓòÉΓòÉ

Now you will perform a query to find the lines in the PAYROLL program source
files where the regular_emp class is used:

  1. Select Query Object from the Browse pull-down. The Query Object window
     appears.

  2. Select regular_emp - class from the Object List in the Objects entry field
     if it is not already selected.

  3. Select Usage for the Scope filter.

  4. Click on the Query push button to start the query.

 The source file containing the first usage of the regular_emp class is
 displayed with the usage string highlighted.

     Look at the Occurrences list to see the list of all the usage occurrences
     of the regular_emp class in the PAYROLL program.  Select Occurrences 
     Next from the Text pull-down or press F12 to display the next occurrence
     of the class in the source files.


ΓòÉΓòÉΓòÉ 7.7. Displaying Object Definitions ΓòÉΓòÉΓòÉ

Another useful feature in the Text window is the What is function. It displays
the definition of the selected item in a pop-up window.  To display the
definition of a usage occurrence, of the regular_emp class that you selected
before:

  1. Display the first usage occurrence (1 of 4) of the regular_emp class by
     selecting it from the occurrences list.  The PAYROLL.CPP file is displayed
     on the Text window with the occurrence string highlighted.

  2. Now, from the View pull-down, select What is.

     This is what you see:

 Note:  When you are selecting text for a What is action, follow the same
        guidelines outlined in Tips for Copying into the Object List.


ΓòÉΓòÉΓòÉ 7.8. Saving and Editing Source Files ΓòÉΓòÉΓòÉ

Standard editing functions, such as Cut, Copy, Paste, Undo, Find, and Replace
are provided in the Edit pull-down in the Text window. You can only edit text
in the Text window when the Browse Only option in the Edit pull-down is
disabled.

Experiment by using these editing functions to edit the PAYROLL program
source-code files.  You do not have to save your changes. If you want to save
your changes, use the Save as option in the Text pull-down.  You can save your
changes to a file that you name when you are prompted in the Save as window.

Note:  Any changes you make to the source files will not be reflected in future
       searches and queries until another compile is done, and the updated
       browser files are reloaded into the database.


ΓòÉΓòÉΓòÉ 7.9. What You Have Learned ΓòÉΓòÉΓòÉ

You have just completed Lesson 5: Using the Text Window. You have learned how
to:

 o Display the occurrences list using Occurrences  List from the Text
   pull-down

 o Rotate through the sequence of occurrences using Next and Previous

 o Use Search Database to search for all the source files in the browser
   database

 o Select an object from the Text window and copy it into the Object List

 o Use Query Object to query an object from the Text window

 o Find a text string in the displayed file

 o Display the definition of a selected object in the text window using What is

 o Enable editing in the Text window by disabling the Browse Only option

 o Edit text in the Text window using editing functions provided in the Edit
   pull-down.

 Minimize the Text window and then continue to Lesson 6: Finishing Up.


ΓòÉΓòÉΓòÉ 8. Lesson 6: Finishing Up ΓòÉΓòÉΓòÉ

This lesson shows you how to end the browser session, but first, a few words
about unloading browser files.


ΓòÉΓòÉΓòÉ 8.1. Unloading Browser Files ΓòÉΓòÉΓòÉ

If you have more than one browser file loaded into the database, you might want
to unload one to exclude the program components (or facts) associated with it
from future searches or queries. When you unload a file from the browser
database, all the browser windows are reset (that is, cleared of their
contents), and the Object List is emptied.

To unload the PAYROLL.BRS file from the browser database:

  1. Return to the Browser Control window.

  2. From the Database pull-down, select Unload.  The Unload Browser File
     window appears listing all the files that are currently loaded in the
     database.

  3. In this case, only the PAYROLL.BRS file is loaded.  Select it and then
     click on the Unload push button to unload the file.

 The browser database is now empty, and all the browser windows are cleared.


ΓòÉΓòÉΓòÉ 8.2. Ending the Browser Session ΓòÉΓòÉΓòÉ

To end the browser session, select Close browser from the first menu bar option
in any browser window, or press F3.

When you exit from the browser, the browser database is emptied of its
contents.

Note:  You do not have to unload browser files before you exit the browser.


ΓòÉΓòÉΓòÉ 8.3. The End ΓòÉΓòÉΓòÉ

You have now reached the end of this tutorial. You have learned all the major
functions and features of the browser.

Experiment with other functions of the browser using the PAYROLL program or a
program of your own.  You can use the on-line help for guidance.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Trademark of the IBM Corporation


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

A filter is a parameter that limits a search or query so that only the data
that fulfills the criteria specified by the filter is displayed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The access specifier of an object determines the access other objects can have
to it.  Access specifiers apply equally to all class member objects: member
functions, member data, nested classes, and enumerators.

The access specifiers are public, private, protected, and friend.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

A dangling arc is an arc that points to an invisible node in the graph.
Dangling arcs originate from collapsed nodes.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

To select a node in the graph, position the mouse pointer on the node you want
to select and press mouse button 1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

An arc is a directed line that connects two nodes.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

A Child of a node is a direct or first level descendant of the node.