server.htm

## Understand Client

Understand for Ada listens for requests from other programs. The command line version of the program "understand_ada" is used to send requests to the Understand for Ada server.

A client request may be to tell the Info Browser and all synchronized view windows to show information about an particular entityname. Or a request may be to show a particular view of a specific class or file. Or to configure or analyze a project, perform a hypergrep search, or to find a class.

The understand_c program accepts commands in the following forms:

Perform some action on an entity using the current Understand session:

understand_ada -n[ame] entityname -file filename [-line line
-col column] actionCommand

Perform some action on an entity specifying the Understand project to use:

understand_ada [-db database] [-new | -existing] -n[ame] entityname -file filename [-line line -col column] actionCommand

Perform some action on a file entity:

understand_ada [-db database] [-new | -existing] -efile entity_filename actionCommand

Open any file (not project-dependent):

understand_ada -openfile filename

### Specifying the Project Database

When launching understand_ada commands, the existing Understand for Ada window can be used or a new Understand for Ada window can be launched and a new project loaded.

To use the existing Understand for Ada window and current project, omit the -db specifier on the command line. You can also specify -exisitng to override any possible user-customized preferences set in the current project. For example:

understand_ada -existing -name myEnt -file file.adb -line 37 -ib

will load the Info Browser of the current Understand session with the specified entity.

To launch a new instance of Understand, use the -db specifier. You can also specify -new to override any possible user-customized preferences. For example:

understand_ada -db myproj.uda -new -name myEnt
-file file.adb -line 37 -ib

will launch a new session of Understand, load the database myproj.uda, and show myEnt in the Info Browser.

### Specifying the Entity

To specify the entity to be shown, use the following command specifiers:

If the entity is a project file:

-efile filename

Or, if the entity is not a file:

-name entityname -file filename [-line line -col column]

where:

* efile - the name of the file entity you wish to learn more about. This is a required argument if the entity is a file.
* entityname - the name of the entity you wish to learn more about. This is a required argument. Partial names will not be matched.
* filename - the name of a file where the entity is referenced. This is a required argument.
* line - An optional argument indicating what line number the entity you want to learn about is found at. This further clarifies where you are looking at an entity. Again, most often used when undestand_ada is launched from an editor or other source browsing program.
* column - An optional argument indicating at what column position the entity you want to learn more about is at.

Following is a sample command line to load the Info Browser of an existing Understand session with entity Load_Game which is referenced in the file mahjongg.adb:

understand_ada -name "Load_Game" -file mahjongg.adb -ib

### Opening a File

You can also load any file into the Source Editor. Specify -openfile and the path to the filename:

understand_ada -openfile mahjongg.adb

will open mahjongg.adb in the current directory and load it into the Source Editor of the existing Understand session.

### Action Commands

Many types of actions can be driven by understand_ada.

* -entitymenu - popup the entity menu for the specified entity at the current cursor position.
* -edit_src - open the source for the declaration of the specified entity. This is the same action as a double-click on an entity within Understand.
* -ib - load the Info Browser with the specified entity
* -ibnew - bring up a new Info Browser and load with the specified entity. This is the same action as occurs in Understand when the "Reuse" button is not checked.
* -gv "graphical_menu_string" - show the specified graphical view for the specified entity. See below for list of possible values for graphical_menu_string.
* -gvnew "graphical_menu_string" - show the specified graphical view for the specified entity in a new graphic window. See below for list of possible values for graphical_menu_string.

Graphical menu strings for ADA
Callby
Child Lib Units
Declaration
Declaration Tree
Declared In
Instantiated From
Instantiations
Invocation
Parent Declaration
Parent Lib Unit
Type Derived From
Type Tree
With
Withby

* -edit "entity_menu_string" - open the source of the specified entity for editing. See below for list of possible values for entity_menu_string.
* -editnew "entity_menu_string" - open the source of the specified entity for editing into a new source window. (only available in SDI-mode). See below for list of possible values for entity_menu_string.

Entity Menu Strings for Ada
Body Declaration
Declaration
File
Generic Body Declaration
Generic Declaration
Generic Spec Declaration
Incomplete Declaration
Instantiation Declaration
Private Declaration
Spec Declaration
Stub Declaration

### Example Client Commands

Popup the entity menu for package Board at the current mouse position:

understand_ada -name "Board" -file board.ads -entitymenu

Edit the source file where package Board is defined.

understand_ada -name "Board" -file board.ads -edit_src

Load the Info Browser with the package entity Board:

understand_ada -name "Board" -file board.ads -ib

Show the graphical With view for package entity Board:

understand_ada -name "Board" -file board.ads -gv "With"

### Communication Method

The program understand_ada uses different communication methods based on the operating system it runs on.

On Windows 95/NT, Dynamic Data Exchange (DDE) is used.

On Unix and VMS, sockets are used to send information to the server. Since the possibility of conflicting with other programs using the same socket address is present, the server port used may be specified on the Browser Tab of the Options->Preferences menu. .

If a conflict arises, change the Server Port to another number.

### Editor Synchronization Example

Here is a simple example integrating understand_c to be launched from a text editor. In this case the editor is the inexpensive (but very powerful) editor called "TextPad". It is available on the Internet at http://www.textpad.com.

Note that TextPad (and many other editors) offer internal variables that may be passed to external programs.

In this case we are passing $Sel (text currently highlighted) in as the entity name argument, $File as the filename, $Line as the line number, and $Col as the column where the entity can be found. In this example, the right click menu of the entity will be displayed in the current mouse position and whatever selection is then chosen from the right click menu will be loaded into the Understand window.

Now, after Double Clicking or highlighting on any Ada entity in TextPad, we can choose the Tools->Understand_ada popup menu option to activate Understand's right click menu for that entity. The selection from the right click menu will then be displayed in the Understand for Ada window.

.

Scientific Toolworks, Inc. http://www.scitools.com Voice: (802) 763-2995 Fax: (802) 763-3066 support@scitools.com sales@scitools.com