Setting Up a Session

This section contains the following topics:

Panorama Operation Diagram

MAIN menu

Loading a Makefile

Input Bin List

Creating and Loading a Database

Generating Dynamic Data

Test Coverage

Run-time performance

Menu Bar

Panorama analyzes your code and builds a database of information about it. This happens during a Panorama session when you press the CREATE DATABASE button on the MAIN menu. Panorama uses that database until you exit Panorama or you do one of the following:

CREATE a new database, or

LOAD a previously created database.

NOTE: Because test coverage and performance data are stored in separate data files, you do not need to rebuild the database to examine new data generated by tests run between the saving and reloading of the database (as long as your source code remains unchanged).

Panorama Operation Diagram

Panorama is easy to use. The following is a simplified diagram that shows the basic steps for operating Panorama.

setup.GIF - 12.90 K

MAIN menu

Panorama Main Window

After you have started Panorama C/C++ (see "How to start Panorama C/C++"), the MAIN menu will come up. From here you can perform operations such as specifying the source program you wish to analyze by writing an input bin (.hsi) file, creating or loading a database for the analysis results, or running specific tools in the Panorama C/C++ environment.

The MAIN menu is subdivided into three sections: the menu bar, the tool bar, and the input bin. For more information on the menu bar, see "Menu Bar" . For more information on the input bin, see "Input Bin List".

Most of the commonly-used functions in the menu bar can be easily accessed by pressing the tool bar buttons directly on the MAIN menu.

Tool bar

The following is a brief description of each of the buttons on tool bar of the MAIN menu.

Loadmak.gif - 0.51 K Load makefile: Loads the makefile of the user's program.

loadhsi.gif - 0.46 K Load .hsi file: Loads the.hsi (input bin) file, which specifies the source program.

savehsi.gif - 0.51 KSave .HSI FILE saves the .hsi (input bin) file.

builddbs.gif - 0.54 K Make(create database): Creates the database for your program to store analysis results.

loaddbs.gif - 0.54 K Load .dbs file: Loads the database, which is the repository of all the information gathered from Panorama's static and dynamic analysis of your program.

test.gif - 0.35 K OO-Test: Allows you to plan, run, and measure your testing effort; provides comprehensive multi-level test coverage analysis (classes/function/block/branch/condition/loop boundary/segment/condition-segment).

browser.gif - 0.43 KOO-Browser: Generates active structure charts: function charts, class charts, and overview charts. This button is inactive until you have specified the target program and created the database.

dia.gif - 0.60 KOO-Diagrammer: Generates active logic diagrams: J-Diagrams, J-Flows, and ActionPlus Diagrams. This button is inactive until you have specified the target program and created the database.

sqa.gif - 0.71 KOO-SQA: Generates software quality assurance metrics results: weighted bar graphs, Kiviat Diagrams, object-oriented metrics histograms, multiple metrics diagrams, and reports. This button is inactive until you have specified the target program and created the database.

analyze.gif - 0.47 K OO-Analyzer: Generates active tables and charts on different aspects of your program: classes, functions, complexity, performance,global and static variables, etc. This button is inactive until you have specified the target program and created the database.

subset.gif - 0.44 KSELECT SUBSET Allows you to select a subset of the files in your program, and view only the analysis results for these files. This button is inactive until you have specified the target program and created the database.

stop.gif - 0.41 K Stop:Stops all Panorama C/C++ operations on the current database.

help.gif - 0.44 K Help:Provides on-line help for using Panorama C/C++.

Loading a Makefile

With Panorama C/C++, you don't have to manually specify the source files in your program. Panorama can automatically generate the data base and an input bin file from the makefile of your program.

If your program does not have a makefile, skip to the next section "Input Bin List" .

To load in a Makefile:

  1. From the Panorama MAIN menu, press the LOAD MAKEFILE tool button (the leftmost button in the tool bar).

    The LOAD MAKEFILE menu will come up.

    Ldmakem.gif - 10.17 K
  2. In the FILTER field, type in the directory for your makefile followed by "*"

    All the files in that directory will be listed in the FILES list.

    Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.

  3. Select the makefile by clicking on the filename in the FILES list.

    The filename you have selected will be displayed in the SELECTION box.

  4. Click OK.

    The content of the Makefile will be displayed in the Input Bin

Mainmake.gif - 16.43 K

Now that you have loaded in your makefile, you can directly go to the section "Creating and Loading a Database"

Input Bin List

It is recommended to use a makefile for all purposes. If your program does not contain a makefile, you must first specify the target program to be examined using an Input Bin List.

Note: When the Input Bin List is used, Panorama will only generate static information about your program (no test coverage data).

Specifying the code you want to examine

You can specify the source files and the corresponding CPP directives for your target program in the INPUT BIN on the MAIN menu. You can make a new list each time you start Panorama C/C++, or you can save the list in a Panorama input (.hsi) file for later reloading.

An input bin file can be designed using any text editor.

To design a new Input Bin List using Panorama

1. Click on the EDIT in the MAIN MENU.

2. Type in the source files and the corresponding CPP directives in Panorama’s main window.

savehsi.gif - 0.51 K To save the contents of the INPUT BIN

  1. Press SAVE HSI FILE on the MAIN MENU to bring up the SAVE dialog box.

    The SAVE dialog box will pop up.

    hsisave.gif - 7.04 K

  2. You may type in a new name in the "Selection" area, or in the FILTER field, type in the directory for your .hsi file followed by "*.hsi"

    All the .hsi files in that directory will be listed in the FILES list.

    Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.

    NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.

  3. Select the .hsi file by clicking on the filename in the FILES list.

    The filename you have selected will be displayed in the SELECTION box.

  4. Click OK.

    Check the bottom of the MAIN menu for any messages.

    If you do not want to save your edits, click CANCEL on the SAVE dialog box to close the dialog box.

Composing or modifying an Input Bin list and then saving it in an .hsi file is one way to prepare an .hsi file. Alternatively, you can create an .hsi file with UNIX commands. Change to the directory that contains your source files and use the following command to create an .hsi file:

ls /"path"/*.h /"path"h/*.cc > "your-project".hsi

CPP DIRECTIVES and other analysis options

For Panorama to analyze code correctly, all CPP directives in your makefile must be specified in the input bin.

Panorama recognizes three CPP directives when it parses your list of source file names: -D, -U, and -I.

-Dname: Defines a symbol name for preprocessing. This is equivalent to #define name in the source code.

-Uname: Undefines a previously set symbol name definition. This is the inverse of the -D option.

-Ipathname: Adds a pathname to the list of directories in which Panorama searches for #include files. Panorama searches for #include files in the directory containing the source file, the default include directory, and any directories named using the -I option.

-yH: Indicates also analyzing the system header files included in user programs dynamically and/or statically.

-CC=<compiler> indicates the full path name of the C++ compiler to be used

-cc=<:compiler>:: indicates the full path of the C compilerto be used

-dd=<ddfile path>: Specifies the full name of the ddfiles storing the test coverage data (it has the meaning only in the case that the input-bin file is generated from a makefile automatically)

(See your CPP documentation for more about these directives, and for information about the search order of include files.)

Placement of CPP directives in the input bin is significant in Panorama. Directives that are listed alone on a line in the input bin are considered global and apply to all source and .hsi files listed below them (but may be overridden by options at the top of nested .hsi files). Directives placed immediately after a file name on a line apply to that file only. For instance:

-I/mnt/test/incl

/mnt/test/demo_sparc/exprtst.cc -DSPARC

-CC=/usr/CC/sun4/CC

/mnt/test/demo_sparc/function.cc

/mnt/test/demo_sparc/symbol.cc

The "-I/mnt/test/incl" directive specifies where Panorama will look for header files for all the source files,

The "-DSPARC" directive instructs Panorama to define a macro named "SPARC" which has no value. This is typically used to specify that code between "#ifdef" and "#endif" is to be analyzed. This directive only applies to /mnt/test/demo_sparc/exprtst.cc.

load hsi fileTo reload a previously saved .HSI List

  1. On the MAIN menu, press the LOAD .HSI FILE button.

    The LOAD dialog box will pop up.

    hsiload.gif - 7.22 K

  2. In the FILTER field, type in the directory for your .hsi file followed by "*.hsi"

    All the .hsi files in that directory will be listed in the FILES list.

    Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.

    NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.

  3. Select the .hsi file by clicking on the filename in the FILES list.

    The filename you have selected will be displayed in the SELECTION box.

  4. Click OK.

    Check the bottom of the MAIN menu for any messages.

    The contents of the .hsi file you have loaded will be displayed in the MAIN menu.

    Mainhsi.gif - 15.17 K

You can edit the INPUT BIN using motif text editor operations by clicking the Edit button first.

Creating and Loading a Database

Panorama C/C++ statically and dynamically analyzes your source program and builds a database of information about it. But before Panorama can start its analysis, you must specify the database (.dbs) file for it to store the information.

The OO-Browser, OO-Diagrammer, OO-Analyzer, and OO-SQA buttons on the MAIN menu are inactive until you have either created or loaded a database.

builddbs.gif - 0.54 K To create a database

After you have specified a target program using its makefile ( "Loading a Makefile" ) or an INPUT BIN list (see "Input Bin List" ), you can create a database for you program.

  1. Press BUILD DATABASE on the MAIN MENU.

    The CREATE DATABASE FILE dialog box will pop up.

    Createdb.gif - 6.53 K

    (if you loaded an input-bin file rather than a makefile, Panorama will build the data base with the same name as the input-bin file but have .dbs suffix without showing this dialog box )

  2. You may type in the dbs file name in the "Selection" area, or in the FILTER field, type in the directory for your .dbs file followed by "*.dbs"

    All the .dbs files in that directory will be listed in the FILES list.

    Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.

    NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.

  3. Select the .dbs file by clicking on the filename in the FILES list.

    The filename you have selected will be displayed in the SELECTION box.

  4. Click OK.

    Check the bottom of the MAIN menu for any messages.

    If you do not want to create the database, click CANCEL on the SAVE dialog box to close the dialog box.

If you have used a .hsi file, a static database will be created at this point.

If you have used a makefile to specify your program, both the .hsi file and the database (for test coverage data) will be generated together. Follow the steps below to complete the database creation process.

To generate input bin file and a database

  1. Follow the steps in the section above.

    The DBS AND INPUT BIN FILE GENERATION menu will come up.

    Dbshsim.gif - 11.90 K

  2. Select how the input bin file and database is generated:

    DYNAMIC AND STATIC ANALYSIS -- for while performing instrumenting (for test coverage data).

    You can then select SEGMENT COVERAGE DATA only or SEGMENT + CONDITION COVERAGE DATA.

    STATIC ANALYSIS ONLY -- for while simulating the running of your program.

    This is the faster way to generate a .hsi file. You can use it when you have already “make”-ed your program. Note: To ensure correct result, make sure all the .o files in your program have been created.

  3. Specify the compiling information in the text fields.

    C++ Compiler:

    specify the C++ compiler name for analyzing a C++ program.

    C Compiler:

    specify the C compiler name for analyzing a C program.

    DD PATH indicates the path that the test coverage data files to be generated (this field cannot be modified) (HSI NAME -- the path and the file name of the .hsi file to be generated. But in the new version, the HSI NAME will be automatically determined as the same as the data base name but different suffix (.hsi )).(This field cannot be modified).

  4. Specify the make command information.

    MAKE START DIRECTORY -- the directory in which the make command should be initiated. (this field cannot be modified).

    MAKE COMMAND -- the actual make command typed in when compiling manually, such as "make -f mymkfile."

  5. Select how to build.

    BUILD ALL -- to disregard time dependencies in compiling the program.

    Use it for the first time you generate a .hsi while compiling.

    UPDATE INCREMENTALLY -- to follow time dependencies in compiling the file.

    Use it if you have previously generated a .hsi while compiling, then modified some source files.

    WITH SYSTEM HEADER FILE ANALYSIS - to also analyze the system header files included in the program(It’s spent a lot of time).

  6. Click APPLY.

    An xterm window will pop up. If all the selections and specifications are correct, Panorama will begin to generate the input bin file.

    When the input bin file has been generated, you can select to retain or close the xterm window. To close the INPUT BIN FILE GENERATOR window, press CANCEL.

  7. You can then load the generated .hsi into Panorama for reference. We recommend you not to use the input-bin file to build a data base because the data base must have been built before the input-bin was generated, unless you want to use a nested input-bin file to build a super data base consisting many small and independent programs. See "To reload a previously saved .HSI List"

Note for "static analysis only"

If you have defined a compiler macro "CC=..." in your makefile, you must specify the compiler name in the Panorama command. The default compiler is CC.

After the database has been successfully created, you can activate the individual tools in Panorama by pressing the correct tool bar buttons on the MAIN menu.

stop.gif - 0.41 KNOTE: In some cases you may wish to stop the database creation process. You can do so by pressing the STOP button on the MAIN menu.

loaddbs.gif - 0.54 KTo reload a previously saved database

If you have already created a database from a previous session, you can start a Panorama session by loading an existing database.

  1. On the MAIN menu, press the LOAD DATABASE button.

    The LOAD dialog box will pop up.

    dbsload.gif - 7.09 K

  2. In the FILTER field, type in the directory for your .dbs file followed by "*.dbs"

    All the .dbs files in that directory will be listed in the FILES list.

    Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.

    NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.

  3. Select the .dbs file by clicking on the filename in the FILES list.

    The filename you have selected will be displayed in the SELECTION box.

  4. Click OK.

    Check the bottom of the MAIN menu for any messages.

After the database has been successfully loaded, the tools buttons of the MAIN menu will become active.

Database files and incremental analysis

The first time Panorama C/C++ analyzes your entire program, it creates both an overall database file and various component database files (one for each source file -- .cc, .C, .c, and .h -- in the program). The overall database is stored in the filename you have specified in the CREATE DATABASE dialog box. The component database files are stored in the dbs subdirectory under the directory containing the overall database. These component database files contain all static analysis results for the code you have specified. The overall database file contains the information for linking the component database files to form a database.

Panorama adopts the approach of incremental analysis. It re-builds a component database file only if its source file has been changed. Panorama compares the modification time of the (existing) component database file with its source. If the component database file is missing, or if it is out of date with respect to its source, Panorama will then re-analyze its source. If you wish to force Panorama C/C++ to re-analyze all the source files, just remove the component database files under the dbs subdirectory.

Note: Incremental analysis applies as long as the makefile or .hsi file has not been modified.

Generating Dynamic Data

An important feature of Panorama is its ability to graphically represent data from both static and dynamic analysis of your program in many formats, such as on J-charts in OO-Browser, on J-Diagrams and J-Flows in OO-Diagrammer, on metrics diagrams in OO-SQA, and in tables and charts in OO-Analyzer, in diagrams and reports in OO-Test.

Static analysis data (program structure, complexity, compactness, etc.) are derived directly from your source code. Dynamic data, however, must be generated separately before they can be displayed using different tools.

Where do dynamic data come from?

Dynamic analysis data (performance and test coverage data) must be captured during actual runs of your program. To capture performance or test coverage data, you must run a version of your program that has been compiled using your compiler’s profiling options or the Panorama test coverage data capture utility.

Compiling your code for dynamic analysis

When you specify your program using a makefile, preparation for capturing test coverage data has already been done. Just run your program using OO-Test (see Panorama /OO-Test) to accumulate test coverage data.

To capture run-time performance data, compile your program using your compiler’s -p option. Then run it to accumulate performance data in a mon.out(default filename) file.

Test Coverage

Panorama supports test coverage on many different levels, from the more general class and function levels to the more detailed block, branch, segment, condition-decision and condition-segment levels. You can select the right level depending on your testing needs.

Panorama not only shows the percentage of code executed, but also the number of times it has been executed.

To view test coverage data in OO-Browser, OO-Diagram, OO-Analyzer, and OO-SQA, you must first capture the data using OO-Test (see Panorama/OO-Test).

Run-time performance

What is run-time performance?

The run-time performance data show (in milli-seconds) the duration of execution of a function incorporated in the program. The number of times the function was called is also shown. The performance data come from real execution of the program under testing.

Receiving the run-time performance data

The performance data are generated by compiling (using your compiler) the source code with the -p option and then running the program. The performance data are kept in a mon.out profile file generated while the executable program is running.

In order to prepare performance data for a Panorama session, you should follow these steps:

  1. Make the program by adding the -p option into the makefile.

  2. Run the program to generate the mon.out profile.

NOTE: preparing the performance data and preparing the test coverage data should be done separately.

Menu Bar

The menu bar on the MAIN menu contains six buttons: FILE, TOOLS, SUBSET, PROPERTIES, ABOUT, and HELP. Some of the buttons open up pull-down menus with additional selections.

FILE pull-down menu

Click on the FILE button on the MAIN menu bar to open the FILE pull-down menu

Filemenu.gif - 1.66 K

The LOAD .HSI FILE and SAVE .HSI FILE buttons allow you to specify your source program (see "Input Bin List" ). The LOAD DBS, and CREATE DBS buttons allow you to specify the corresponding database (see "Creating and Loading a Database"), just like the tool bar buttons on the MAIN menu.

Clickon PRINT to print the content of the INPUT BIN to the default printer.

Click onQUIT to exit Panorama C/C++.

TOOLS pull-down menu

Click on the TOOLS button on the MAIN menu bar to open the TOOLS pull-down menu

Toolsmen.gif - 1.98 K

From the menu, click a button to run OO-Browser, OO-Diagrammer, OO-SQA, OO-Analyzer, or OO-Test. It is same as pressing the corresponding tool bar buttons on the MAIN menu. Click STOP to stop all applications of Panorama.

SUBSET pull-down menu

Sometimes you may be interested in only a small part of the software system. For example, instead of looking at test coverage results for the entire system, you may wish to view the results for just the part you have written. You can do so using subset selection from the MAIN menu.

After you have first create or load an input bin list, you can then select from the list of files in your source program a subset of files that you are interested in. Then in each individual Panorama tools you initiate from the MAIN menu, you can specify whether to follow this subset selection. If you choose to follow it, only the analysis results for the selected files will be shown and tabulated accordingly.

Selecting a Subset

  1. Click SUBSET on the MAIN menu to open the SUBSET pull-down menu.

    Subsetme.gif - 1.21 K
  2. Click SELECT.

    The SUBSET SELECTION box will come up.

    setsub.gif - 7.40 K

    You can also open the SUBSET SELECTION box by pressing the SELECT SUBSET button on the MAIN menu.

    Note:

    If the file list is empty, please check the following:

    An input bin list has been created or loaded (see "Input Bin List")
    The .hsi relative path has been correctly set. (see "PROPERTIES)
  3. Select the subset of files you are interested in.

    All the files in the program are selected as default.

    To unselect a file, click the filename.

  4. Click OK.

The subset selection has been completed. You can change it (by following the same steps) only if no tools are active.

Viewing Subset Selection

  1. Click SUBSET on the MAIN menu to open the SUBSET pull-down menu.

  2. Click VIEW.

    Viewsubs.gif - 7.60 K

    You can view the subset selection you have made, but you cannot modify it.

  3. Click CANCEL to exit the window.

To modify your subset selection, use SELECT SUBSET (see "Selecting a Subset" above).

PROPERTIES

You can set properties for how your source code should analyzed. This should be done before creating the database.

  1. Click PROPERTIES on the MAIN window.

    The PROPERTIES menu will come up.

    Properti.gif - 3.82 K

  2. Choose source program style.

    The old versions of C++ do not support true nested scopes. If WITH NESTED SCOPE is not selected, Panorama will analyze C++ programs in which nested types are “hoisted” to the scope of enclosing class; otherwise the implementation of true nested types is assumed.

  3. Select the directory to which the content of the .hsi file in the input bin is relative.

    For example, if all your source files are in ~/project/src, and the input bin lists only the source filenames (no path), then you should set .HSI RELATIVE DIRECTORY to ~/project/src.

    The default is the directory from which you started Panorama C/C++.

  4. Press OK.

ABOUT

Click ABOUT on the menu bar to get more information about the Panorama C/C++ environment you are using, such as how many individual tools have been activated.

About.gif - 11.73 K

back to Table of Contents