TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Importing and Exporting

The importing and exporting commands control the relationships between library contexts, especially with regard to inter-subsystem compilation dependencies.

About This Chapter

The major topics covered in this chapter are:


Imports and Exports to Control Architecture

Imports and Exports

Imports and exports control the relationships, especially compilation dependencies, among Summit/CM views (Apex/Summit) in different subsystems or Rational Subsystems (Apex/ClearCase).

In Apex/Summit, a view in a subsystem can export units that it contains to make those units visible to views in other subsystems. Conversely, a view in a subsystem can import units that are exported by views in other subsystems.

In Apex/ClearCase, a Rational subsystem can export units that it contains to make those units visible to other Rational subsystems. Conversely, a Rational subsystem can import units that are exported by other Rational subsystems.

When a library context imports an interface from another library context , the imported unit becomes visible to the importing Apex/Summit view or Rational Subsystem. This visibility makes it possible for the importing Apex/Summit view or Rational Subsystem to use the imported interface in compilations.

An importing Apex/Summit view or Rational Subsystem is sometimes referred to as a client. An exporting library context is sometimes called a supplier. A client can compile programs using interfaces defined by a supplier only if the client imports those interfaces from the supplier. This client/supplier relationship is illustrated in Figure 5 (Ada) and Figure 6 (C/C++).

Figure 5 Clients and Suppliers for Ada

Figure 6 Clients and Suppliers For C/C++

In other words, clients are granted visibility only to units that are exported by suppliers.

A collection of units exported by a supplier is called an export set. A supplier can have different multiple export sets, each of which specifies different units.

How Library Contexts Import Units

When a client needs to compile a program using units exported by a supplier , the client must specify the export set that contains the required units. When a client imports a specified export set, the client gains visibility only to the units in the specified export set —— not to any other set of units exported by the supplier.

To specify imports, you can execute the commands described in Table 3.

Table 3 Commands that Specify Imports
Operation
Apex/Summit Command
Apex/ClearCase Command
Import a library context
Control > View Properties
Compile > Architectural Control > Imports - Add Imports button
Stop importing a library context
Control > View Properties
Compile > Architectural Control > Imports - Remove Imports button
Display all imports
Control > View Properties,
Control > Show > Imports
Compile > Architectural Control > Imports

The commands listed in Table 3 affect the files in the library context's Imports subdirectory as described in Table 4.

Table 4 Files Affected by Commands that Change Imports
Filename
Contained list
Description.cfg
Hierarchical explicit imports
Description.export_sets
Export sets to use for each explicit import
Mutual_Description.cfg
Library contexts in the same mutual importing set. Each line has the form <subsystem name> <set name>

The files listed in Table 4 are text files, so you can opt to edit them directly instead of using the commands. To display them in an editor window, choose Control > Show > Imports (Apex/Summit) or Compile > Architectural Control > Imports (Apex/ClearCase) to bring up the Imports window and choose Import Description, Mutual Description, or Export Set Description from its Navigate menu.

The architectural issues of layering and using relationships between subsystems were discussed earlier. Now you need to provide an implementation of such relationships by setting up importing relationships between library context. The importing relations are established betweenlibrary context because they are the physical instances of subsystems and import relations can change over time and exist in multiple versions. One system configuration may have a specific set of import relations and another may have different importing relations representing, for example, the importing relations at different points in time in the life of the system. The architecture that includes the importing relations, evolves over time as does the code and other parts of the system.


Importing Overview

You use import operations to manage the inter-subsystem compilation relationships of Summit/CM views (Apex/Summit) or Rational subsystems (Apex/ClearCase). A client can only compile against the interfaces of a supplier if the client imports the supplier. (The precise visibility of symbols between the two Summit/CM views or Rational subsystems is further controlled by the export characteristics of the supplier.)

To establish the import relationships, specify a set of explicit imports for a client. You can specify the explicit imports as parameters to the import command or by editing the import description file in the Imports directory.

Once the explicit imports have been specified, the import process conceptually proceeds in two stages. First, a set of implicit imports are computed. The implicit imports are Summit/CM views or Rational subsystems in the import closure of the explicit imports. The client has indirect compilation dependencies on the implicit imports. The full set of imports is the union of the explicit and implicit imports.

The second stage of the import process performs various checks on the consistency and compatibility of the full import set. The checks are listed below:

Import Files

User input to the import process is maintained in files in the Imports subdirectory of the library context. When an import command is run, these files are updated appropriately. You can also edit these files directly to change the imports of a library context. The current contents of the file are used each time the imports are analyzed. The files are:

Explicit and Implicit Imports

There are two kinds of imports: explicit and implicit. A union of explicit and implicit imports is called a full import set.

Implicit imports are library contexts imported by the library context in an explicit import but not imported by the library context itself. They are the library contexts that the imported library context need to compile successfully.

Implicitly imported library contexts must comply with the following consistency and compatibility checks:

Figure 7 Implicit Import Library Contexts

Hierarchical Relationships and Mutual Importing

Tree-structured, noncircular import relationships are called hierarchical relationships.

Hierarchical importing can be relaxed by grouping library contexts into mutual importing sets. One way to think of a mutual importing set is as a single compilation context distributed across views of multiple subsystems for Apex/Summit or as a single compilation context distributed across Rational subsystems for Apex/ClearCase. Each library context in a mutual importing set has:

A mutual importing set is formed when each library context in the set declares itself to have a mutual import relationship with the other members of the set. This is accomplished through the import command or by editing a text file in each library context of the set.

Once a set is formed, an import change to any member results in a change to all members. A library context can be a member of, at most, one mutual import set.

For Apex/Summit, to create a mutual importing set:

1 . Choose the command Control > Change View Properties.

2 . The Change View Properties dialog box is displayed.

3 . In the Change Imports area, list all the other views in the mutual importing set.

4 . Click the Import Each Other radio button.

Import Obsolescence

When imports are successfully computed they are said to be valid as long as the information from which they were computed does not change. Library contexts can be imported or compiled only if they have valid import information. Import information becomes invalid if:

When imports are invalid they must be re-analyzed to make them valid. Imports are not made invalid when the input files in the Imports directory are modified.

Its useful to think of the import dependencies between library context as similar to the compilation dependencies that exist between program units. Library contexts with valid imports are analogous to program units that are semantically consistent. Changing the import characteristics of supplier library contexts is similar to recompiling supplier program units, in both cases the clients or program units must be re-analyzed.

Apex/Summit

For example, consider a view upper.ss/tom.wrk, which imports from view lower.ss/tom.wrk.

Below is a list of circumstances under which the imports of upper.ss/tom.wrk would become invalid.

Apex/ClearCase

For example, consider a Rational subsystem upper.rss, which imports from Rational subsystem lower.rss.

Below is a list of circumstances under which the imports of upper.rss would become invalid.

System Descriptions

System descriptions describe the logical import relationships for a system. For Apex/Summit, these are independent of specific views. System descriptions contain a specification of the relationships between supplier subsystems and client subsystems. For Apex/Summit, these must be realized in actual views of the subsystems.

System descriptions are represented in files with the extension .sysd. A system description file contains lines of the form:

System description files can also contain comment lines that begin with the character "#".

To generate system descriptions that describe the import relationships of actual views, run the show_imports command with -generate_sysd option. For Apex/Summit, the import relationships of a system description may be applied to a set of views by using the accept_import_changes command.

System Description Example

Apex/Summit

The following is an example of the contents of a system description file. In this description, views of subsystem upper.ss import from views of subsystem middle.ss using the export set "restricted". Views of subsystem middle.ss import from subsystem lower.ss using the default export set.

Apex/ClearCase

The following is an example of the contents of a system description file. In this description, views of Rational subsystem upper.rss import from Rational subsystem middle.rss using the export set "restricted". Rational subsystem middle.rss imports from subsystem lower.rss using the default export set.

Import Architecture of the Avionics Example

This section shows the dependency architecture of the avionics example. You will refer to subsystems by their layer name and subsystem name for brevity, leaving off the /projects/avionics prefix that appears on each name. The import architecture here is described in terms of subsystems; when a system configuration is actually built, the library contexts of that system configuration are the actual objects that have the import relationship.

To see all of the subsystems, bring up a directory viewer window on the directory /projects/avionics. Click View > Expand. The resulting window is illustrated in Figure 8.

Figure 8 Expanded Figure Directory Window

Figure 9 is simplified diagram showing the main import relationships follows. It does not include all imports because almost all subsystems import packet_routing and math_library.

Figure 9 Import Relationships for the Avionics Example

Setting Up Imports

Imports are a property of each library context. Setting up imports is different depending on whether you are using Apex/Summit or Apex/ClearCase.

Apex/Summit

All view properties can be displayed and edited using the View Properties dialog which is brought up by the Control > View Properties menu item.

To set the imports for each view, follow the following steps. You will use as an example importing math_library and memory_management into radar:

1 . In the View Properties dialog, fill in the view name, /projects/avionics/navigation/radar.ss/rev.1.wrk in the Properties of view field.

2 . Press return or click Reset to show the current view properties for that view. If no view have been imported yet, only views imported implicitly by the model will appear. These usually contain the package Standard (Ada) or predefined header files C/C++).

3 . Type the full names of each view to be imported to the Add field of the Imports area and press return or click Add. Repeat until the Imports list field shows the desired list of imported views.

In this example, enter:

4 . Click Apply to set the imports for the view.

When the import change is applied, Summit/CM checks that all the imports are legal and updates internal structures so that compilation will work properly. In the event some imports are illegal, messages indicating this are displayed. See the next section for more details of what happens in case of errors during importing.

Figure 10 Setting Imports of radar.ss, Imports Part of Dialog

There are some other ways to set imports that can be easier in some cases. You can use the Change View Properties command to change the imports of a number of subsystems in a single operation. The Change View Properties dialog box is brought up using the Control > Change View Properties menu item.

Changing Imports for a Number of Subsystems

If there are a number of subsystems that need to have the same views imported, you can follow these steps.

For example, all of the subsystems in the flight_control directory (rudder, wings, hydraulics, fuel_management, and engines) import os_interface, math_library, and packet_routing. You can set all of these imports in a single operation:

1 . Choose Control > Change View Properties to bring up the Change View Properties dialog box.

2 . Add the views whose imports are to be changed to the Change Properties of Views list field at the top of the dialog.

If appropriate, a wildcard naming expression can be added. In this example, enter:

3 . Press Return or click Add.

    Note: If there were other objects listed in the list field, they should first be removed by selecting them and clicking Remove.

4 . Click the Change Imports button.

5 . Click Add/Replace button to specify that imports are to be added.

6 . Add the names of the views to be imported to the Change Imports list field.

In this example, enter:

Note: If you are entering several similar names, after the first is entered, you can retrieve it and edit it rather than retyping from scratch. To do this, type Control-P in the Add field or left-click on the History Icon next to the Add field.

7 . Press Return or click Add.

8 . Click OK or Apply to add the listed imports to the listed views.

Figure 11 View Properties Dialog Box

Requested and Actual Imports

The importing process can become quite involved because Apex tries to make sure that imports are consistent and they all exist. When setting up or altering imports there may be cases where a library context is imported before it is created, for example. This is legal, but Apex will issue error messages indicating that the current imports are not legal as of the time that they were set.

Apex keeps two lists of imports: the current legal, actual imports, and the requested imports. If all the imports are OK, these two lists are identical. If not, the actual imports are a subset of the requested imports.

For Apex/Summit, the View Properties dialog box, illustrated in Figure 11, can show both lists. There are radio buttons in the Imports area to select which list is displayed. If the lists are identical, the buttons are disabled.

For Apex/ClearCase, use the Compile > Architectural Control > Imports command.

Mutual Imports

In the architecture of the avionics system, you had no hierarchical relation between the processes and memory_management subsystems. They were interdependent. To implement this relationship, you will form a mutual import set containing these two subsystems. Effectively, both will import each other.

Apex/Summit

Since establishing this mutual import relationship requires affecting more than one subsystem, you cannot use the View Properties dialog as before.

Create mutual imports using the Change View Properties dialog box, which is started from the menu item Control > Change View Properties. Follow these steps to establish a mutual import relationship. Use the processes and memory_management subsystems as an example.

1 . Choose Control > Change View Properties to bring up the Change View Properties dialog box illustrated in Figure 12.

Figure 12 Change View Properties Dialog Box

2 . Add the names of the views to be imported into each other to the Views list field by entering their names in its Add text entry field. Press Return or click Add.

    Note: If there were any other objects in the Views list, select them and click Remove.

3 . Check the Change Imports check box.

4 . Click the Import these views into each other button in the Change Imports area.

5 . Click OK or Apply to establish the mutual importing relationship.


Exporting Overview

For program units in a supplier to be visible to a unit in a client, the client must import the supplier and the supplier must export the program units. Program units that are not exported are not visible to the client.

An export set is a set of units exported from a particular library context. Units are always exported into a particular export set. Different export sets can contain different units. When a client imports a supplier, the client specifies an export set in the supplier that will be used. The client is visible only to the units included in the export set being used.

The create_export_set command creates export sets that are represented by files in the Exports directory of each library context.

Special Export Sets

There are two special export sets:

Export Files

User input to the export process is maintained in the Exports subdirectory of the library context. When an export command is run, the unit to be exported is added to the appropriate export description file:

User specification of export sets in the client is maintained in the Imports subdirectory of the client. This information describes which export set in the imported library context to use to establish visibility.

Default Export Set

Each library context has a default export set (specified by the switch DEFAULT_EXPORT_SET), which specifies the export set for the clients to use when they do not specify a set. Commands that take an export set parameter may specify the string default_export_set to denote that the supplier's default export set is to be used.

Client Usage of Export Sets

Clients (importers) specify the export set to use for imported library contexts, by either specifying value in the -set option of the import command or by editing the Description.export_sets file in the Imports directory. When no export set is specified for an imported library context, the default export set of the imported library context is used.

Creating an Export Set

You can create an export set by executing the Control > View Properties (Apex/Summit) command or the File > New > New Export Set command.

When you execute the File > New > New Export Set command, Apex displays the File New Export Set dialog box. When this dialog box opens, you can create an export set by specifying its name and clicking OK or Apply.

Deleting Export Sets (Apex/Summit)

To delete an export set being exported by a supplier:

1 . Execute the Control > View Properties command.

The View Properties dialog box is displayed.

2 . When the View Properties dialog box opens, select the name of the export set you want to remove in the Export Sets list field.

3 . Click the Remove button next in the Export Sets area.

4 . Click OK button or Apply to remove the export set.

Changing the Imported Export Set (Apex/Summit)

To change the export set imported by a client view:

1 . Execute the Control > Change View Properties menu command.

The Change View Properties dialog box is displayed.

2 . Enter the name of the new export set you want to import in the Export Set part of the Change Imports area

3 . Add the name of the imported view to the list in the Change Imports area.

4 . Click Replace Existing.

5 . Click OK or Apply to change the export set.


Context Switches

The following context switches can be used to control import and export operations.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS