Getting Started

Rational Apex uses the same Apex development environment as native systems. The Apex development environment is discussed in detail in the Getting Started Guide and Programming with Apex Guide. Please refer to those documents for a general discussion on using Apex.

However, embedded systems are, by nature, more complex than native systems. This complexity requires that additional steps be taken to use Rational Apex. These are discussed in this chapter.

---

Overview

The basic steps that must be taken to use Rational Apex products are described in the following sections.

• Create a Working View For Your Application
• Compile Your Application
• Link Your Application
• Target Control
• Run and Debug your Application

---

Create a Working View For Your Application

1 . Using File > New > New Subsystem, create a subsystem to contain your working view.

2 . Using File > New > New View, select a Tornado model and create a working view. To display a list of the models available, use the Navigation icon to the right of the Model field in the New View dialog box.

Note: Tornado views are distinguished by the presence of extra entries in the Policy/Switches file: WIND_BASE, and WIND_REGISTRY.

---

Compile Your Application

1 . Move your files and includes into the working view using File > Copy Object. Specify the list of files to copy and click OK. After this step is completed, you have a list of files in your working view.

An alternative method for populating the working view is to use the Compile > Maintenance > Import Text Files command. This command renames files and restructures code when necessary to conform to Apex conventions such as one package per file, file names being the same as package names, and separate files for spec and body. This is the preferred method for importing code that is not already in an Apex view.

2 . Use Compile > Code to compile. You can compile single units or entire lists of units.

---

Link Your Application

1 . Use Compile > Link to create an executable program. Specify a unit containing a main procedure or function as the argument for linking.

Compile > Link with no arguments links all the units in a view that have a pragma Main declaration.

Note: Both Compile > Code and Compile > Link cause Apex to evaluate unit dependencies and recompile units as needed. You can often skip the intermediate Compile > Code step. This is generally more feasible for small programs.

---

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 the PowerPC "board" model when creating your view, the Logical Target field will contain "power.rx_ppc.board".

You may change the value of the Logical Target field if you wish. The string "power.rx_ppc.board" 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 tabs, fields, and buttons of this dialog are described in detail in File > New > New Physical Target. Once you have created the new physical target, the new physical target name appears in the Map dialog 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. For VxWorks or LynxOS, select those tabs. The logical values required change with the tab.

• 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.

Usually 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.

---

Run and Debug your Application

The previous step established the Current Target which is used when running or debugging your application. To run the application, select File > Run. The Run dialog is displayed. Click on one of Run's Options if you wish to change the available cross specific options. Normally, the defaults can be used. Hit OK. Your application is downloaded and run. Any output is displayed in an Apex output window.

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. This brings up the Apex Debugger GUI allowing you to debug your code.

Changing default timeouts

The default timeout for downloading a file in Tornado is 240 seconds. Very large files can often take longer than this to download.

To change the default download timeout execute the following command in a tornado windSh.

-> ? set wtxCmdTimeout(wtxObjModuleLoad) X

where X is the number of seconds before timeout.