![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Online Reference Summary This appendix consists of the online reference screens that are supplied with the Rational Compilation Integrator (RCI). Included in this section are descriptions of the various commands and switches that are unique to the RCI.
The following topics are covered:
- RCI > Create Target Library
- RCI > Delete Target Library
- RCI > Refresh Target Imports
- RCI > Compare To Target
- RCI > Accept Target Changes
- RCI > Create Script
- RCI > Copy to Target
- Batch Mode Procedures
- RCI Switches
RCI > Create Target LibraryThis command creates a target Ada library (Target Directory) that corresponds to the specified host view. (Depending on your RCI customization, the command builds the elements of the Ada library required by your target compiler, including the Ada program library and import information.) You can specify multiple views, but only if each already has an associated target directory and only if the Target Directory field is left blank and Destroy Existing is set; this causes the target libraries associated with the specified host views to be rebuilt.
If the Target Directory does not already exist on the target, Create Target Library creates it and associates it with the selected host view. If the RCI Target Directory does exist on the target but is not an Ada library, Create Target Library converts it into an Ada library before associating it with the host view. If the RCI Target Directory exists on the target and is already an Ada library, Create Target Library just associates it with the selected view.
Note: Do not assign two views from the same subsystem to the same target library, unless your customization specifically requires this structure.
Once it has created the target library, Create Target Library marks all units in the host view 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).
The first time you create a target library for a host view, you must specify the Target Directory. You should also specify the Machine, if different than the host, when a target library is initially created. When rebuilding an existing target library, you can use either or both of these fields to override the settings contained in the view's switch file.
Target Directory Field
Use this field to specify the full name of the target directory. The first time you create a target library for a particular host view, you must specify the Target Directory. When rebuilding an existing target library, this field is optional.
The Target Directory must not be nested within an Apex view.
Machine
Use this field to specify which machine, if different than the host, performs target operations (such as compilation and linking). When rebuilding an existing target library, if this field is not supplied, the command uses the existing Machine setting for the target library.
Rebuild Existing Check Box
Setting this button causes the RCI to first destroy the existing target library (both Ada library and directory) corresponding to the selected host view, then build the specified library (if the Target Directory field is left blank, this causes the existing library to be rebuilt). The values of RCI_TARGET_DIRECTORY and RCI_COMPILATION_PLATFORM are used to determine the default settings of the Target Directory and Machine fields. To override these values, enter the desired value(s) in the appropriate field(s). If this option is not selected, and the new target library is in a different location from the existing target library, the existing target library is "orphaned"; that is, your host view no longer contains any information about its existence.
Note: Create Target Library may or may not be implemented from one RCI customization to another. Also, your customizer can modify the operation of Create Target Library. For additional information, check the RCI Customization Guide.
RCI > Delete Target LibraryThis command deletes the target library (both the Ada library and the target directory) 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, your customizer can modify the operation of Delete Target Library. For additional information, check the RCI Customization Guide
RCI > Refresh Target ImportsThis command makes 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 the Apex Control > Maintenance > Refresh or Control > Maintenance > Remodel commands are invoked.
Note: Refresh Target Imports may or may not be implemented from one RCI customization to another. Also, your customizer can modify the operation of Refresh Target Imports. For additional information, check the RCI Customization Guide
RCI > Compare To TargetThis command compares each selected program unit —— or each program unit within a single selected view —— with its corresponding file on the target and displays the name of each unit, using a warning message to indicate those that do not match and a positive message to indicate those that do match. This command only checks units that the RCI has recorded in the RCI target names file.
Compare To Target also lists the name of each unit that is registered in the RCI target names file but for which no target file exists.
By Time Stamp and By Textual Comparison buttons
By default, Compare To Target determines that a host unit and target file do not match by comparing the host unit's edit time stamp with the target file's edit time stamp. If the target file's time stamp is later than that of the host unit, the units do not match. Selecting By Textual Comparison forces Compare To Target to instead perform a character-by-character comparison of the contents of the host unit and the target file. The two files do not match if any differences are found.
The APEX_OUTPUT_FILTER environment variable should specify the display of positive (those marked with a `+++') and warning (those marked with a `!!!') messages. The default value for APEX_OUTPUT_FILTER produces the correct behavior.
Note: The default method that the RCI uses to determine that a host unit does not match its corresponding target file is customizable, and in fact may not rely on time stamps as described here.
RCI > Accept Target ChangesThis command compares each selected program unit —— or each program unit within a single selected view —— with its corresponding file on the target and copies each unit that has been changed on the target into the host program unit to which it corresponds. This command only checks units that have been recorded in the RCI target names file.
By Time Stamp and By Textual Comparison buttons
By default, Accept Target Changes determines that a target file has changed by comparing the target file's edit time stamp with the host unit's edit time stamp. If the target file's time stamp is later than that of the host unit, Accept Target Changes assumes that the target file has been changed. Selecting By Textual Comparison forces Accept Target Changes to instead perform a character-by-character comparison of the contents of the host unit and the target file. Irrespective of the method used for comparison, if any differences are found Accept Target Changes assumes that the target file has been changed and copies it to the host.
Note: The default method that the RCI uses to determine that a target file has been changed is customizable, and in fact may not rely on time stamps as described here.
RCI > Create ScriptCreate Script creates a batch compilation script that, when executed on the target compilation platform, compiles and (optionally) links the specified units (and those units in the closure of the specified units).
All units specified to Create Script must belong to a single host view.
Each unit in the execution closure of the specified units must have been coded on the host. (If any of the units are not coded, the RCI creates the script for the coded units, and it issues warnings about the units that are uncoded.)
To create a script for all of the Ada units in a given host view, select the view, using the standard file locator on the Create Script dialog. Since the RCI can only generate a given batch script for units selected from a single host view, specify either a single view or one or more units from a single view using the Create Script dialog's standard file locator.
Warning: The RCI assumes that after you generate a batch script you will immediately execute that script, compiling each unit in the script on the target. Unless you execute every script you generate, in the order you generate them, the RCI state information for the units in the host view may not reflect the actual state of the target library, and subsequently-generated batch scripts may fail when executed on the target.
The RCI takes the following steps to construct the list of units to be compiled by the batch script:
- 1 . Start with the list of selected units, or all units in the selected host view.
- 2 . Remove the uncoded units.
- 3 . Add to the list those units that constitute the execution closure of the selected units.
- 4 . If Include All Units is not selected, remove from the list all units that are not obsolete, that is, those units that have not been coded since they were last included in a script.
The script is named batch.scr by default. Script Name allows you to specify your own filename for the batch compilation script created by the Create Script command. This can be either a simple name or a relative or full path name. The command adds an .scr extension if you have not supplied one.
Create Script does not overwrite an existing batch script. If the file specified in the Script Name field (or batch.scr) already exists, the RCI generates an error message, and does not overwrite it.
Create Script automatically creates a buildlist file into which it writes the names of all program units that the batch script will compile. You can use this file as indirect input for transferring host units to the target when using the Copy To Target command. The RCI generates the buildlist's filename from the script's filename by changing the .scr extension to .bl.
Link Main Units Button
Controls whether or not the batch compilation script contains commands to link main units. Link Main Units is selected by default. If this option is not selected, the batch script compiles, but does not link, the specified units when you execute it. In any case, if a specified unit is not a main unit, the RCI does not generate a link command for that unit.
Include All Units Button
Enters into the batch compilation script all units in the execution closure of the specified program units. By default, Create Script only includes in the batch script those units that have been changed on the host since they were last included in a script. You should use this option if you want to recompile the entire system on the target. Note that creating scripts with this option can lead to inconsistencies; if a view is built, but not its clients, those clients become obsolete on the target.
Copy Units to Target Button
Copies each unit needed by the batch compilation script to the target compilation platform when the script is created.
When you have selected the units and options, click on Apply or OK in the dialog box button bar.
RCI > Copy to TargetCopy To Target can be used to copy different kinds of files from the host to the compilation platform: Ada program units; the contents of buildlists; and ordinary files.
In RCI batch mode, Copy To Target transfers each selected host Ada program unit from a batch view into the target directory that is associated with that host view. The RCI bases the target name for each transferred Ada unit on the host unit name and depends on the naming scheme that your customizer defined for your RCI customization.
In addition to Ada program units, you can also select buildlist files (generated by the Create Script command, and identified by a `.bl' filename extension). If you specify the buildlist, Copy To Target transfers each program unit named in each selected buildlist file, along with any individually-selected Ada program units.
If you select a file that is not an Ada unit and not a buildlist then Apex will download that file without any interpretation of the filename. The mechanism used to download the file is the same as for Ada units that is defined for your RCI customization.
RCI Target Machine Field
The RCI Target Machine field allows you to specify the compilation platform to which you want the specified units copied.
When you have selected the units and/or buildlist files to be copied, click on Apply or OK in the dialog box button bar.
Note: Your customizer can modify the method that the RCI uses to transfer files (copies or symbolic links). For additional information, check the RCI Customization Guide.
Batch Mode ProceduresThis page outlines some of the more useful procedures that you can use when working with units in an RCI batch-mode view.
Verifying Batch Mode
You can verify batch mode operation for a given view by checking (with Control > Show > Switches) the RCI_COMPILATION_MODE switch, which is found in the /Policy/Switches file for the view in question. This switch should be set to "batch". This switch file also contains the RCI_AUTO_TRANSFER switch, which determines whether the RCI automatically transfers units to the target when they are coded. If RCI_AUTO_TRANSFER is set to "False", you must transfer all units requiring recompilation to the target before you execute the batch compilation script.
Note: The RCI_COMPILATION_MODE and RCI_AUTO_TRANSFER switches may not be present in the Switches file. If the RCI is unable to find an explicit definition for a particular switch, it uses the switch's default value. The RCI_COMPILATION_MODE switch defaults to "interactive". The RCI_AUTO_TRANSFER switch defaults to "True".
Compiling in Batch Mode
- 1 . Select those units that you want to compile and code them, along with all units in their execution closure (Compile > Code).
- 2 . Use RCI > Create Script to generate a batch script. If the RCI_AUTO_TRANSFER switch was set to "False" when the units were coded, you can select the Copy Units To Target option to transfer them when the RCI creates the script. Note that since the host and target are connected via NFS, you do not need to transfer the script to the target directory.
- 3 . If the RCI_AUTO_TRANSFER switch was set to "False" when you coded the units, and you chose not to transfer the units when the script was built, use RCI > Copy to Target to transfer those units needing compilation to the target directory.
- 4 . If the compilation platform is the same as the host machine, select the batch script and execute it either by double-clicking on it or by using File > Run. Otherwise log on to the compilation platform and execute the batch script there.
Retrieving Associated Files
Associated files are those files that are generated as a result of target compilation. These files can include assembly listing files, cross-reference listings, debug tables, etc. Because the target is connected to the host via NFS, it is usually not necessary to transfer these files back to the host. If it is necessary, you can use the File > Copy Object command to transfer these files from the target to the host.
Your customizer can modify the RCI to automatically transfer associated files. Check the RCI Customization Guide. for more information.
RCI SwitchesSwitches that affect a particular Apex subsystem or view are located in subsystem_or_view_name/Policy/Switches. The RCI uses the default value if you have not entered the switch in the file. The RCI-specific switches include the following:
- 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 during compilation actions in the host view. Its value is taken from the setting of the Host Only button in the RCI Options subwindow that appears when File > New > New View or File > Copy Object is used to create an RCI view. This switch can take a value of "True" or "False" (the default value is "False"). Host_Only views may have target directories, which are used to maintain consistency between host and target imports. One frequent use of host_only views is to represent precompiled target APIs.
- RCI_TARGET_DIRECTORY: this switch identifies the target directory corresponding to the RCI view.
Use Control > Show > Switches to display and edit these switches.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |