TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Batch Processing

This chapter addresses how to use the RCI in batch mode to perform batch processing. Under batch mode, promote and demote operations affect only units on the host; when you are ready to compile units for the target, you use batch operations to copy units and build a batch compilation script. You can then copy the script to the target compilation platform and execute it.

This chapter includes the following sections:


Overview Of Batch Mode

Apex's compilation model is optimized to support quick turnaround of changes. For example, Rational Apex users can make changes incrementally for the best turnaround.

The RCI provides added flexibility for compilation by allowing you to work either in interactive mode or in batch mode. Each mode has its advantages —— whereas interactive mode maintains continuous consistency between host and target units, batch mode decouples host and target compilation and may improve turnaround in cases where compilation is time-consuming.

The following subsections describe:

Compilation

When you use the RCI in interactive mode, coding a set of units on the host causes the RCI to transfer each unit to the target library and then compile it on the target, starting with the first unit in the compilation order. When the target compiler successfully compiles a unit, the RCI changes that unit's state on the host to coded; consequently, the coded state indicates that a unit is compiled both in the host view and in the target library.

When you use the RCI in batch mode, coding a set of units on the host simply determines whether a proper compilation order can be generated for the units and their suppliers and, if so, marks each unit as "codable" by changing its unit state to coded. Although the RCI may transfer the units to the target as part of the coding operation (if the RCI_AUTO_TRANSFER switch is set to "True"), it does not compile these units in the target library. Consequently, you can edit and code units on the host with no target compilation overhead.

When you want to compile units for the target, bring the units to the coded state on the host and then use RCI batch operations to:

After you have built the script and copied units, you can execute the batch script using Apex or operating system commands.

The RCI in batch mode allows you considerable flexibility in your development process —— you can code, edit, and re-code units on the host without causing target compilation (although target semantics are checked); conversely, you can force the target recompilation of coded host units without having to re-code them on the host.

The Batch Script

When you generate a batch script for a unit (or any number of units from a single host view), the RCI looks at the compilation closure and selects units that are coded on the host, determines which units in the closure require target compilation, and determines the order in which to compile them. It then generates a script that invokes the target compiler (and, optionally, the target linker) for those units. Finally, the RCI generates a file that contains the name of each unit that the batch script will compile.

The Create Script command normally generates an incremental batch script in that it includes only obsolete units in the script. Obsolete units are units that have been coded on the host since the last time they were entered into a batch script. This behavior can be overridden; you can specify that the batch script compile every unit in the compilation closure of the selected units (but doing so is risky, as you may make some units on the target obsolete by compiling their suppliers).

Note: The RCI assumes that after you generate a batch script you will immediately execute that script, compiling on the target each unit that was entered into the script. Unless you execute every script you generate, 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. Note also that units that fail to compile on the target for any reason will still appear to be coded on the host.

For efficiency, the RCI can be customized to generate the batch script so that it makes the fewest possible calls to the target compiler. (This may or may not be true for your specific customization. Check with your customizer or installer for information on how the RCI constructs batch scripts for your target.) Instead of invoking the target compiler once for each Ada unit, RCI batch scripts may invoke the target compiler once for each set of units that belong to the same Ada program library.

A simple batch script is shown here:

Note that customizers can use batch extensions to cause the RCI to parse the results of a batch script execution and to make units on the host obsolete if the execution fails.

Target Directory and Consistency Management

The RCI provides interactive commands that automatically create and destroy target libraries when you create and destroy views on the host. You can use these commands regardless of which mode is in effect.

When you use the RCI in batch mode, you use the interactive commands to manage target directories, because the base RCI does not provide special batch operations for library management. Note that the RCI library extensions can be customized to generate batch-style library-management commands. Check with your customizer to see whether such commands are available at your site. More information on customization can be found in the RCI Customization Guide.

When you use the RCI in interactive mode, consistency between the host and target directories is maintained automatically, provided that all code development takes place on the host. Such consistency can be maintained because information about target unit state is sent back to the host with each interactive command. Consequently, updating a unit's state to coded on the host guarantees that it has compiled successfully on the target.

When you use the RCI in batch mode, it is more difficult to maintain consistency between host and target directories. In batch mode, there may not always be an automated way to determine whether the compilation script executed successfully on the target. It is up to you, the developer, to execute each batch script immediately after it is generated, thus maintaining consistency between host and target unit states.

When to Use Batch Mode

You may find it preferable or even necessary to use batch mode, particularly in the following cases:


Enabling Batch Mode

The following switches in Policy/Switches control, for a given view, whether the RCI transfers units to the target when they are coded and which mode is in effect:

For example, the following entry in .../Test.ss/target_view.wrk/Policy/Switches causes all RCI operations within target_view.wrk to take place in batch mode:


Using Batch-Mode Operations

Building a Batch Script

In batch mode, coding a set of units marks them as codable in the RCI state file ("codable" means that a proper compilation order can be generated for the units and their suppliers, but says nothing about their state in the target library) and optionally transfers them to the target library. You must then use the RCI > Create Script command as a separate operation to build a batch script for these units.

Before you can build a batch script for a given unit, the units you want to enter in the script must be in the coded state. The closure may include units that were promoted to the coded state in either mode. In particular, it may include units in imported views that are not in batch mode. In fact, building a batch script for interactively coded units is useful for rebuilding an application, either in the same set of target directories or in a new set.

If any unit you've selected for the script is not in the coded state, the RCI omits that unit from the script and produces a warning message.

The Create Script Command

RCI > Create Script creates a batch compilation script in the view context which contains commands to target-compile each selected program unit (and its compilation closure) and optionally link the main unit or units. The RCI computes the compilation ordering and includes those program units needed to compile and link.

The Include All Units option includes in the batch compilation script all coded units in the compilation closure of the selected units, rather than only obsolete units (those units which have been modified since the last time a script was created).

The RCI > Create Script command also creates a buildlist file which contains an ordered list of the selected units to compile in the batch compilation script. The buildlist file can be specified as input to the RCI > Copy To Target command, causing RCI > Copy To Target to transfer to the target all of the units that the batch script will recompile.

Figure 10 The Create RCI Script Dialog

After you have built the batch compilation script, you can transfer the needed program units to the target compilation platform, and execute the batch compilation script.

The RCI > Create Script dialog is shown in Figure 10. It should be used as follows:

1 . Select those units you want the batch script to compile, using the file selector at the top of the dialog. Note that all selected units must be from a single host view. To compile all Ada units in a particular host view, simply select the view name using the file selector.

2 . If you want to give the script a filename other than the default ("batch.scr"), specify the desired name using the Script Name field. Script Name can be a simple name or a relative or full pathname. If you do not include it as part of the name, the RCI appends the ".scr" extension. You cannot use an existing filename as the script name. The buildlist file that RCI > Create Script automatically generates will have the same name as the batch script, with a ".bl" extension substituted for the batch script's ".scr" extension.

3 . If you do not want the RCI to link the selected main units when you execute the script, click on Link Main Units, deselecting it (it is selected by default).

4 . If you want to compile all units in the compilation closure of the selected units, instead of limiting the script to recompiling those that the RCI considers obsolete, click on Include All Units.

5 . If the RCI_AUTO_TRANSFER switch is set for the view in which the selected units reside, those units were transferred to the target when they were coded. If the RCI_AUTO_TRANSFER switch is not set, and you want to transfer those units being recompiled to the target at this time, click on Copy Units To Target.

After you have filled out the dialog box, left-click the OK or Apply button on the Create RCI Script dialog box to create the batch script.

Transferring Host Units

Note: NFS customizations of the RCI by default do not actually make target copies of host units. Instead, the RCI creates a symbolic link in the target directory to each "copied" host unit. Check with your customizer for information about how your RCI customization transfers units.

In batch mode, you can transfer units to the target library in one of three ways:

1 . If the RCI_AUTO_TRANSFER switch is set to "True" (its default setting) for a host view, the RCI transfers units in that view to the target library whenever you code them.

2 . If you selected the Copy Units To Target option when building your batch script, the RCI transfers to the target all units that the batch script needs at the time that you build the script.

3 . You can use the RCI > Copy To Target command to explicitly transfer units from a host view to its corresponding target library.

The Copy To Target Command

To use RCI > Copy To Target, select those units that you want to copy using the file locator found at the top of the Copy To Target dialog box, and left-click the OK or Apply button.

In addition to Ada program units, you can select buildlist files (generated by the Create Script command, and identified by a ".bl" filename extension). The RCI transfers each program unit named in each selected buildlist file, along with any individually-selected Ada program units.

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 has defined. Check with your customizer for more information about target-naming for your customization.

Executing the Batch Script

The script generated with the RCI > Create Script command is a command-language script for the target platform. Because the host is linked to the target via NFS, you do not need to transfer the script to the target in order for it to be executed, although you can copy it if desired. Execute the script from the target's command prompt just like any other shell script. This is typically done simply by entering the script name (use an absolute path name unless the host directory is already in the target's execution path) and press Enter. If the host and the target are the same, you can use Apex's File > Run command to execute the batch script.

Note: Before executing a batch compilation script, you must transfer all the units that the script references to the target. If you execute the script without making all of the appropriate transfers, your results may be invalid (even if you don't get error messages from the target compiler).

Retrieving Associated Files

Associated files are those files that the target compiler and linker generate as a result of target compilation operations. These files can include assembly listing files, cross-reference listings, debug tables, etc. Because the target is connected to the host via NFS, you do not usually need to copy these files back to the host. If it is necessary, use Apex's File > Copy Object command to copy these files from the target to the host.

Your customizer can modify your customization to automatically transfer associated files. More information on customization can be found in the RCI Customization Guide.


Troubleshooting Batch-Mode Operations

Batch compilations may fail on the target even when you have coded all of the host units successfully. This could happen for any of the following reasons:

If a batch-script compilation fails, you can recover as follows:

1 . Examine the output of the batch script to determine the problem. Determine which units failed to compile and why.

2 . Fix the failed units on the host and re-code them.

3 . Use the RCI > Create Script command to generate a batch script for the units you fixed. Run this incremental batch script on the target.

Note that some target compilers fail for all units in a library if any unit in that library fails to compile. In such cases, generating an incremental script is not enough. To recover, you need to re-generate the batch script to include all of the units in the view. Do this by invoking the Create Script command with the Include All Units option and specifying the units listed in the buildlist file from the failed build. Be sure to specify a new name for the script and buildlist files that the incremental build will generate.


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