Getting Started

Using Rational Apex Embedded for Rational Exec requires some configuration:

• You must set up a board support package (BSP) for your target board.
• You must configure a kernel.

This chapter details the steps to use if your product installation contains a model BSP for your target board. If you cannot use one of the BSP's provided, follow the steps in "Building a Custom Configuration" in Configuring Rational Exec to create a new or modified model. Then use these steps with your customized BSP.

Use the following steps as a guide to get started using Rational Exec with an existing BSP and the default kernel:

• Create a Working View for Your Application
• Compile and Link Your Application
• Target Control
• Download TDM.
• Download the Kernel.
• Debug your Application

---

Create a Working View for Your Application

Every Apex view must reside within a subsystem.

Note: The concepts of subsystems and views are discussed in the "System Architecture and Rational Subsystems" chapter of the Concepts Guide and a detailed discussion and example of both subsystems and views are in "Creating Subsystems and Views" in the Rational Apex (Native) Programmer's Guide.

1 . To create a subsystem for your working view, select File > New >New Subsystem.

2 . Next, select File > New > New View.

In the New View dialog:

• Type a name for the view in the Name field.
• The Options Tab is selected by default.

  The Other Tab contains pull-down menus to change the permissions of your view.

  The RCI Tab contains the options for integrated development using the Rational Compilation Integrator. For more information, see the RCI User's Guide.

  The Shadow Tab provides options for linking a view to a directory on a PC. For more on this, see the Client/Server Concepts Guide.

  In the Options Tab:

• Use the View Type pull-down to select either Release or Working.
• Model Selection: In Rational Exec, the Cross radio button is selected by default.
• Model: Selecting the navigation icon to the right of this text field will bring up a navigation dialog designed to help you select the correct model. The construction of view names (including model views) is detailed in "View Naming Conventions" in the Configuring Rational Exec Guide.

New View - Select New Model dialog

• Language: Select either Ada 83 or Ada 95 from the pull-down menu.
• Target Family: Select a target family from the pull-down menu. Selecting anything other than All sensitizes the next pull down menu, Specific Target.
• Specific Target: Use this pull-down to select your specific target board. If a simulator option exists, select it. Using a simulator requires no BSP work on your part.

  Note: The simulator is not available for Intel Architecture or M68000 Family targets. If your target is one from these target families, you have two options:

  • Select a model for one of the existing BSP's.
  • Use File > New > New BSP to create a new BSP for your specific target. This will create a new model. Then return to this dialog, and enter your newly created model in the File > New > New View dialog's Model: field.
• Numerics Mode: Select "Relaxed" if you want to use Relaxed Mode Numerics (RMN).
• Click on your choice...
• Click OK

The construction of these view names is detailed in "View Naming Conventions" in the Configuring Rational Exec Guide.

• Imports: Click on the Navigation Icon to the right of the Imports: field. The New View - Imports dialog establishes the relationships between this view and views in other subsystems. The concepts are discussed in the "Imports and Exports" chapter of the Concepts Guide. and a detailed description is in "Imports and Exports" in the Rational Apex (Native) Programmer's Guide.
• Place storage in ... By default, a view's storage is placed in it's parent subsystem. If you wish to use disk space from another location for your view, select Place storage in directory, and fill in an existing directory in the text location.
• Visit the new view is selected by default.
• To create the view, click OK.

---

Compile and Link Your Application

Move your program files and includes into the working view.

To copy files:

• Select File > Copy Object to access the Copy Object dialog.
• Use the Add: and Destination: fields to specify the list of files to copy.

  The Control Tab radio buttons provide the selections that manipulate the CM status of the files being copied. A detailed discussion of Summit/Configuration Management (CM) is in Using and Customizing Summit/CM.

• Click OK.

  This command is described in the online Reference Guide.

To import files:

• Use the Compile > Maintenance > Import Text Files command to access the Import Text Files dialog.
• Use the Add: field to specify the files to import.
• Click OK.

  This command is also described in the online Reference Guide.

After this step completes you will have a list of files in your working view.

• Compile your program from the Compile > Code dialog.
• Link your program from the Compile > Link dialog.

  These commands are described in the online Reference Guide.

---

Target Control

• In your working view, select File > Run.

Determine the Logical Target

The Logical Target field

When you created a view, you obtained a Policy/Switches file based on the model you used. All Apex Embedded models include a LOGICAL_TARGET_NAME switch. The value of this switch is used to initialize the Logical Target field.

For example, if you chose a PowerPC simulator model when creating your view, the Logical Target field will contain "power.rx_ppc.issim".

You may change the value of the Logical Target field if you wish. The string "power.rx_ppc.issim" is provided as a default to help you identify the kind of target you are using. But you could change the name to "my_testing_board", or even "fred" if you wished.

Changing the Logical Target value will make visible a toggle enabling you to make your newly specified Logical Target the default for your current view.

• To change the value permanently for the view, edit the Switches file in the Policy directory. Change the value for the switch LOGICAL_TARGET_NAME.
• To change the value for this immediate execution only, change the Logical Target: field in the Run dialog.

• Click OK or Apply.

Map the logical target

• Since the logical target has not been mapped, a popup asks if you would like to map it. Click Yes.

  In the Map your_logical target to Physical Target dialog, the mapping dialog, the value for your Logical Target: is supplied.

  • If physical targets have been created, double click on the physical target in the List of Physical Targets: field.
  • If you need to create a new physical target, click the Create New Physical Target button. This will bring up the New Physical Target dialog. The new physical target name appears in the Physical Target: field.
• Click OK to return to the Run dialog.

Supply Logical Target Data:

Note: Under Physical Target Kind:, the Rexec Tab is selected.

• Click the Alternatives Icon to the right of the Target Interface: field to display the logical values.

  The target Interface indicates the runtimes your target is using and, for Rational Exec, the method of communications.

The defaults of the Debug, Set I/O Redirection, Set Cross Run Options, and Collect Trace Data options are adequate. These buttons are covered under File > Run in the online Reference Guide.

• Click OK to run the program. Output is displayed in an Apex output window.

After running the program, the mapping from logical target (and the information you entered about the physical target) remains valid from one session to the next. Since a default value for the logical target is obtained from your view's LOGICAL_TARGET_NAME switch, you can simply visit the view, and select File > Run.

---

Download TDM.

TDM must be downloaded onto the target system. Guidelines are provided in "Download TDM" in the Configuring Rational Exec Guide. Note that the guidelines are different for each target board.

---

Download the Kernel.

From within the application view select File > Download to bring up the Download dialogs.

The name of Download Kernel is filled in.

Make sure that Download Kernel is checked.

Click OK to start downloading the kernel.

---

Debug your Application

To debug your application, select File > Debug.

Notice that, by default, the Auto Load Program toggle is on. This indicates that your application will be downloaded automatically by the debugger.

Click OK to bring up the Apex Debugger GUI allowing you to debug your code.

Warning: The '....' that are displayed are not shown until an end of line is encountered. This makes it appear that nothing is going on for long periods of time when downloading over slow communication lines.

Additional information is available in Linking and Executing Programs and in Debugging.