TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Getting Started

This chapter shows you the typical steps taken when working with the RCI in interactive mode. These steps are:

This chapter assumes that you are working with an existing Apex subsystem and host view containing coded Ada units. All Ada units should be under Summit/CM control.

Batch mode operations are covered in Batch Processing.


Before You Start

Before you use the RCI, check to see that your host search path contains the path to your target compiler's bin directory. Add it to your search path before you use the RCI. Check your customization documentation for more information.


Creating an RCI View

RCI views are created using the standard Apex mechanisms. You can construct RCI views in two different ways:

Creating an RCI View Based on an Existing Host View

To create an RCI view from an existing view, select the view and use the Apex File > Copy Object command. The dialog for this command is illustrated in Figure 4.

Figure 4 Using File > Copy Object to create an RCI view

Specify the full name (with optional extension) of the RCI view using the Destination field. The Copy Views file selector should indicate the view that you are copying.

Left click on the Copy Views button to display the View Copy Options dialog. Fill out this dialog as follows:

1 . If the view which you are copying is not an RCI view (or is an RCI view for a different target), select RCI on the Language Dropdown Menu on the Options Tab and specify the model appropriate for your target in the New Model field. For example, on a Solaris platform, the RCI model may be:

2 . Select the RCI TAB and specify the name (full or relative pathname) of the target directory in the Target Directory field.

3 . The name in the Compilation Platform field identifies the target compilation machine; you can leave it blank when the target compilation platform is the same as the host or if the view is Host Only.

4 . Select Host Only if you wish to prevent the target compiler from being invoked when units in the view are coded (for example if the view corresponds to a pre-compiled target library).

5 . Select Interface Only (on the Others tab) if the view will contain only specifications.

Fill out any of the remaining fields as appropriate for your particular application.

After you have filled out the dialog boxes, left-click the OK or Apply button on the Copy Object dialog box to create the RCI view.

This procedure creates the new RCI view (and target directory, if requested), copies the contents of the host view into it, and operates on the Ada units as appropriate to reach the specified Recompile to State.

Creating an RCI View Without an Existing View

To create an empty RCI view, use the Apex File > New > New View... command. Figure 5 shows the New View dialog as it is used to create an RCI view.

Fill in the dialog box as follows:

1 . Name identifies the simple name (with optional extension) of the RCI view to be created.

2 . Verify that the Subsystem field correctly identifies the subsystem in which you want to create the RCI view.

3 . On the Options tab, select RCI on the Language drop down menu.

4 . Fill in the Model field with the RCI Model to be used for the new view. For example, on a Solaris platform an appropriate model might be:

5 . Select the RCI tab and specify the name of the target directory (full or relative pathname) in the Name field.

6 . The name in the Machine field identifies the target compilation machine; leave it blank when the target is the same as the host, or if the new view is Host Only

7 . Select Compile on Host Only if you wish to prevent the target compiler from being invoked when units in the view are coded (for example if the view corresponds to a pre-compiled target library).

8 . Select Interface Only (on the Others tab) if the view will contain only specifications.

Figure 5 Creating a new RCI view

Fill out any of the remaining fields as appropriate for your particular application. Use both the Basic and RCI tabs.

After you have filled out the dialog boxes, left-click the OK or Apply button on the New File dialog box to create the RCI view.

Changing or Rebuilding the Target Library for an RCI View

A target library is typically associated with an RCI view when you create the view. However, if you discover at some point that you need to associate an RCI view with a different target library, or if you did not create the target library during view creation, use the RCI > Create Target Library command. You can also use this command to rebuild an existing target library for one or more host views.

Figure 6 The RCI > Create Target Library dialog box

Figure 6 shows the Create Target Library dialog box. Use this dialog as follows:

The operation of the command depends on your customization. Rational's sample customizations take the following actions. If the target directory does not already exist on the target, Create Target Library creates it, converts it into an Ada library, and associates it with the selected host view; If the target directory does exist, and you select Rebuild Existing Target Library, the existing target directory is destroyed, recreated, converted into an Ada library, and then associated with the selected host view. If the target directory exists, and Rebuild Existing Target Library is not selected, one of two things happens:

Once the target library has been created, all units in the host view are marked as requiring recompilation.

When you create a target library for a view that is imported by others, the importing views' imports are made obsolete. Before you compile units in one of the importing views, you must refresh its imports (use Control > Maintenance > Refresh).

Rebuilding a Target Library

To rebuild the target library for one or more RCI views:

1 . Choose RCI > Create Target Library.

2 . Use the file selector to indicate the views whose target libraries are to be rebuilt. Click on Rebuild Existing Target Library.

3 . Left-click the OK or Apply button on the Create Target Library dialog box.

Changing the Target Library

To change an RCI view's target library:

1 . Choose RCI > Create Target Library.

2 . Use the file selector to indicate the view whose target library is to be changed.

3 . Specify the new target directory in the Target Directory field.

4 . If operations are to be performed in the target library by a machine other than the host, specify the target machine in the Machine field.

5 . If a target directory is already associated with the host view, and you do not wish to reuse it as-is, click on Rebuild Existing Target Libraryg.

6 . Left-click the OK or Apply button on the Create Target Library dialog box.

Note that if you change an RCI view's target library and do not select Rebuild Existing Target Library, the original target library still exists but there is no longer an association between it and the RCI view.


Transferring Units to an RCI View

If your RCI view was created from an existing view (using File > Copy Object), the units in the host view have already been copied to the RCI view. If the units are in a single view and are under CMVC control, you can use Control > Update Objects to accept them into the RCI view. If the RCI view was created using File > New > New View, you can use File > Copy Object to transfer units into the RCI view.

To transfer units that are under CMVC control from another view into an RCI view with Control > Update Objects, fill out the Update Objects dialog as follows:

1 . Use the Views field to specify the RCI view into which you want the host units to be transferred.

2 . Use the Source or Destination Views field to specify the view from which you want the host units to be transferred.

3 . Click on Make identical to views below.

4 . Press OK or Apply to transfer the units.


Examining and Setting Switches

Before compiling and linking the units in your RCI view, you may want to check the values of those switches that affect the operation of the RCI.

There are three general areas where switch values can be found:

1 . Session Switches: Switches that affect your particular session are specified using UNIX environment variables.

2 . Default compiler and linker options are specified by your customizer in the comp_option_file and link_option_file files in the model view, which are copied into your view when it is created. The full set of legal options is defined by your customizer in the comp_option_symbol and link_option_symbol files in your view's Compiler Key. The order in which the options are applied when the target compilation or link command is generated is defined in the comp_option_symbol and link_option_symbol file in the Compiler Key.

You can assign compiler or linker options on a unit by unit basis in your view by associating a value with a unit name, or you can assign values to <default> to use the option with all units in the view. To override the default, specify your overrides in view_name/comp_option_file (or view_name/link_option_file, as appropriate).

A sample comp_option_file enabling the compiler's "verbose" mode for all units follows (the examples that follow assume options have been defined with the names verbose, list and minor_optimize; this will most likely not be the case in your customization, so don't try these examples without suitable modification):

To specify "verbose" mode for all units in the view except unit foo.1.ada:

The order of the options on the line in your file does not matter; the customization determines the order in the command line. You can break a line with a backslash (\) to continue, except inside brackets (<>).

To specify arguments with an option, add a colon and the argument after the option name. Note that the following example would be in the view's link_option_file:

If the option has more than one argument, precede each additional argument with a colon. Arguments are assigned by position. The maximum length for an option and arguments is 512 characters.

3 . Switches that affect a particular subsystem or view are located in subsystem_or_view_name/Policy/Switches file. Among these switches is the COMPILER_KEY switch, which indicates which compiler key view will be used when compiling units in this view. Switches specific to the RCI are also found in this file. Currently, these switches are:

  • RCI_AUTO_TRANSFER: the value of this switch is meaningful only if the RCI_COMPILATION_MODE switch is set to "batch". In batch mode, this switch controls whether or not units are automatically copied to the target when they are coded. This switch defaults to "True".
  • RCI_COMPILATION_MODE: if RCI operations in this view are to take place in batch mode, this switch should be set to "batch". The default value for this switch is "interactive".
  • RCI_COMPILATION_PLATFORM: this switch identifies the machine used to perform operations (such as compilation) in the target directory.
  • RCI_HOST_ONLY: If set to True, this switch indicates that the RCI takes no action on the target compilation platform when the compiler is invoked on units in the view. Views with this switch set to True can still have target directories specified, to enable operations which update target library hierarchies or search paths to locate the corresponding target library for all host view import relationships.

    Its value is taken from the setting of the Host Only button in the RCI Tab that appears when File > New > New View or File > Copy Object is used to create an RCI view.

  • RCI_TARGET_DIRECTORY: this switch identifies the target directory corresponding to the RCI view.

    Sample Switches entries follow:

Note: The above switches may not all be present in the switch file for a specific view. If the RCI is unable to find an explicit definition for a particular switch, it uses the switch's default value.


Analyzing, Coding, and Linking

Units are analyzed, coded and linked in RCI views just as they are in host views, using Compile > Analyze, Compile > Code, and Compile > Link, respectively.

When you analyze an Ada unit in an RCI view, the unit's semantics are checked against those allowed by the target compiler.

Coding of an Ada unit in an RCI view depends upon whether the view is configured for batch or interactive operation and whether or not the view is "Host Only".

Compile > Link is only meaningful in an RCI view that is set up for interactive operation; the command links the selected unit(s) using the target linker and places the resulting executable(s) in the target library.

Figure 7 and Figure 8 show an RCI view on the host and its corresponding target directory on the target.

Figure 8 illustrates an RCI view after the spec and body of Hello (Hello.1.ada and Hello.2.ada, respectively) have been coded and Hello.2.ada has been linked on the target, Figure 8 illustrates the target directory corresponding to the RCI view in Figure 7. This example is RS6000-specific.

Figure 7 An RCI view with host units

Figure 8 Target directory corresponding to an RCI view


Accepting Target Changes

By default, the RCI does not actually make target copies of Ada units. Instead, it creates a symbolic link in the target directory to each Ada unit in the RCI view on the host. Consequently, changes made to Ada units in the target directory are automatically reflected in the host versions of the changed files.

Because the RCI normally does not maintain separate target copies of Ada source files but instead uses symbolic links, RCI > Compare To Target and RCI > Accept Target Changes —— which determine inconsistency by performing a comparison of the host and target files —— add little value. If your RCI has been customized so that it maintains separate target source files, these commands can be used to detect and correct source file inconsistencies.


Deleting RCI Views and Ada Units

Figure 9 illustrates the File > Delete Object dialog, which you use to delete objects within Apex. File > Delete Object can delete Ada units within RCI views, as well as RCI views themselves.

When deleting an Ada unit within an RCI view, the command may take no action on the target (only the host version of the unit might be deleted), depending on how your customization was implemented.

When deleting an RCI view, you have the option to delete the target directory associated with the view as well. To do this, select the Delete the RCI target directory of each view button on the File > Delete Object dialog.

Figure 9 Using File > Delete Object to delete RCI views


Deleting Target Directories

Use RCI > Delete Target Library to delete the target library corresponding to each specified host view. Prior to deleting a target library, the RCI deletes all Ada source files and any working directories that reside in the target library.

To delete one or more target libraries, use the file locator to select the host views to which the desired target libraries correspond. When you have selected all such host views, click on Apply or OK in the dialog box button bar.

Note: Delete Target Library may or may not be implemented from one RCI customization to another. Also, the operation of Delete Target Library can be modified by your customizer. For additional information, check the documentation for your RCI customization.


Refreshing Target Imports

Use RCI > Refresh Target Imports to make target library and host view imports consistent. The RCI does this by updating the imports for the target library that corresponds to each specified host view so that the imports are consistent with those of the specified view.

To refresh the imports for one or more target libraries, use the file locator to select the host views to which the desired target libraries correspond. When you have selected all such host views, click on Apply or OK in the dialog box button bar.

The RCI > Refresh Target Imports operation is automatically performed when Apex refreshes imports through the Control > Maintenance > Refresh or Control > Maintenance > Remodel commands.


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