![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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 ArchitectureImports 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.
The commands listed in Table 3 affect the files in the library context's Imports subdirectory as described in Table 4.
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 OverviewYou 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:
- There can be no circularities in the import relationships. For Apex/Summit, see Hierarchical Relationships and Mutual Importing for a discussion of the conditions under which this restriction can be relaxed.
- Imports must be consistent. If a client imports a supplier, the full import set of the client must be a superset of the full import set of the supplier. That is, for Apex/Summit, the closure of the import relationships must produce at most one Apex/Summit view for each subsystem.
- For Apex/Summit, release views can import only other release views.
- For Apex/Summit, frozen release views can import only other frozen release views.
- The compiler keys of the imports must be compatible. (Each compiler defines what compatibility means for it.)
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:
- Imports/Description.cfg
Contains the list of hierarchical explicit imports.
- Imports/Mutual_Description.cfg
Contains the list of Summit/CM views/Rational subsystems in the same mutual importing set.
- Imports/Description.export_sets
Contains the export set to be used for each imported library context. Each line has the form <subsystem name> <set name>.
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:
- Imports must be consistent.
- Implicitly imported library contexts cannot have circular import relationships (except as described in Hierarchical Relationships and Mutual Importing). For example, in Figure 7, if library context v1 imports v2 which imports v3, then v3 is not allowed to import v1.
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 circular import relationship with all other library contexts in the set
- The same set of hierarchical explicit imports
- The same set of implicit imports
- The same compiler key.
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:
- The BUILD_KEY or COMPILER_KEY is changed.
- The imports of any library context in the full import set are updated.
- The BUILD_KEY or COMPILER_KEY switch is changed for any library context in the full import set.
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.![]()
- The imports of lower.ss/tom.wrk are changed to import a new view base.ss/tom.wrk. The imports of upper.ss/tom.wrk are now invalid. Under most circumstances running import -refresh upper.ss/tom.wrk will be enough to revalidate the imports.
- The compiler key of lower.ss/tom.wrk is changed (most likely through the remodel command). The imports of upper.ss/tom.wrk are now 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.![]()
- The imports of lower.rss are changed to import a new Rational subsystem base.rss. The imports of upper.rss are now invalid. Under most circumstances running import -refresh upper.rss will be enough to revalidate the imports.
- The compiler key of lower.rss is changed. The imports of upper.rss are now 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:
subsystem:
subsystem-name
Specifies the name of a client subsystem.
import:
subsystem-name
[(
export-set-name
)]
Specifies the name of a supplier subsystem and optionally the name of the export set to use when importing from the supplier subsystem.
mutual:
subsystem-name
[(
export-set-name
)]
Specifies the name of a supplier subsystem to be included as a mutual import.
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.
# System description for subsystem in /src/subsystems subsystem: /src/subsystems/upper.ss import: /src/subsystems/middle.ss (restricted) subsystem: /src/subsystems/middle.ss import: /src/subsystems/lower.ss subsystem: /src/subsystems/lower.ss
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.
# System description for subsystem in /src/subsystems subsystem: /src/subsystems/upper.rss import: /src/subsystems/middle.rss (restricted) subsystem: /src/subsystems/middle.rss import: /src/subsystems/lower.rss subsystem: /src/subsystems/lower.rss
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.
/projects/avionics/navigation/math_library.ss/rev.1.wrk
in the Add field. Press Return or click Add. Then enter
/projects/avionics/os_interface/memory_management.ss/rev.1.wrk
- 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:
/projects/avionics/flight_control/*.ss/rev.1.wrk
- 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.
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 OverviewFor 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:
- all_units
This set must be created and deleted like any other export set. However, when this set exists, it automatically contains each program unit in the library context.
- no_units
This set is available automatically in all library contexts and specifies that no units are to be visible to clients. There are no user visible files associated with this export set.
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 SwitchesThe 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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |