IBM
Contents Index Previous Next



Executing CPP2SDL


Normally, CPP2SDL is automatically invoked by the SDL Analyzer as part of the make process. Input header files and tool options are then specified in the Organizer. However, CPP2SDL may also be executed as a stand-alone tool from a command shell, and in that case input headers and tool options are given as command line options.

This section begins with a description of the integration with the Organizer and the Analyzer. Then how to execute CPP2SDL from the command line is described. Finally, follows a section on how to run the tool through the PostMaster.

Execution from the Organizer

The most common way to execute CPP2SDL should be from the Organizer. In fact CPP2SDL will be started automatically by the Analyzer once for each import specification symbol it finds in the Organizer view (see Import Specifications to learn about import specifications). The Analyzer executes CPP2SDL by means of the PostMaster as described in Execution from the PostMaster. All messages that are output during the execution will be printed in the Organizer Log Window.

Example 80 : Executing CPP2SDL from the Organizer

Consider a simple SDL system with one block and one process that needs to access some C++ declarations. At system level certain declarations of the C++ header file general.h is used, and at process level declarations of the files f1.h and f2.h are needed. Figure 167 below shows how the Organizer view of this SDL system could look like.

Figure 167 Organizer view with headers to be translated by CPP2SDL

When this system is analyzed, the Analyzer will execute CPP2SDL once for the file general.h, and once for the files f1.h and f2.h. The result of the first translation is a set of SDL declarations that are injected at system level, and thus will be accessible in all scopes. The result of the second translation is a set of SDL declarations that are injected at process level and thus are not accessible in the system or in the block scope.

Adding Import Specifications to the Organizer view

The first step in accessing C/C++ declarations from SDL is to insert a PR symbol at the place in the SDL specification where the C/C++ declarations are to be used. The PR symbol represents the inclusion of the SDL PR that is the translation of the C/C++ declarations.

To specify that this should be an import specification, double-click the PR symbol either in the Organizer or in the SDL Editor to open the Edit Document dialog. In the dialog it is possible to select either C Import Specification or C++ Import Specification.

An import specification can be edited manually by means of the Text Editor (see Import Specifications to learn about import specifications). However, an import specification can also be edited in the CPP2SDL Options dialog described below.

After adding an import specification it is necessary to specify which C/C++ header files are to be translated. This is done by selecting the import specification in the Organizer and then use the Add Existing and Add New commands to select or create C/C++ header files respectively.

Setting CPP2SDL Options in the Organizer

Required options to CPP2SDL may be specified in the Organizer for each import specification by using the CPP2SDL Options dialog. This dialog may be opened from the menu that appears when the right mouse button is pressed on an import specification symbol. Figure 168 shows this dialog.

Figure 168 The CPP2SDL Options Dialog

The fields and buttons of the CPP2SDL Options dialog correspond directly to the command line options described in Command Line Options:

Execution from Command Line

CPP2SDL is invoked from the command prompt by the command:

cpp2sdl [options] <C/C++ header files>

Unless the -post option is set, all messages that are output by the tool, e.g. errors and warnings, will be printed on the standard error stream (stderr).

CPP2SDL will translate the declarations in the specified C/C++ header files, or a subset of these declarations if a suitable import specification is used (see Import Specifications). The resulting SDL declarations will be saved in a file called name.pr, where name is the name of the import specification used. If no import specification is used, name will be the name of the first input header file.The output file will be placed in the same directory from where CPP2SDL is executed.

There is a possibility when running in batch mode to be able to change the CPP2SDL options used in an SDL system. See Batch Facilities.

Normally CPP2SDL options are saved in an import (".is") file. These options will in batch be superseded by CPP2SDL options given in a batch ".sdt" option file.

Command Line Options

The command line options recognized by CPP2SDL are listed and explained below. Note that an option may be abbreviated as indicated by the underlined part of the option name.


Hint:

If you want to preprocess the input headers using a preprocessor that is not supported by CPP2SDL, you can write a simple shell script that wraps the call to the desired preprocessor. The script should conform to the call style that CPP2SDL uses for unknown preprocessors. Then execute CPP2SDL, using the -preprocessor option to specify the script as the preprocessor to use.

Example 81 : Executing CPP2SDL from the command line

% cpp2sdl -preprocessor /usr/ccs/lib/cpp -output 
result.pr -prefix "ptr=p arr=a" -rtti -ref input.h

This command will translate the input header input.h to SDL and write the resulting SDL declarations to the file result.pr. The specified preprocessor `cpp' will be used to preprocess the input. If the input contains pointer or array types, the corresponding SDL names will be prefixed with `p' and `a' respectively. Source references to the declarations in input.h will be generated by CPP2SDL, and Run-Time Type Information is assumed so that dynamic cast operators are generated.

Execution from the PostMaster

As mentioned above, CPP2SDL may be started as a PostMaster client by using the -post option at the command line. As a PostMaster client, CPP2SDL will handle two different PostMaster events.

The reception of a SESTOP event has the expected behavior; CPP2SDL ceases to be a PostMaster client and terminates.

The SECPP2SDLCOMMAND event has an option string as argument. The event will cause CPP2SDL to execute according to the options specified in that string. The format of the option string is the same as when CPP2SDL is executed from the command line (see Execution from Command Line). All messages that are output by the tool will be broadcast to the PostMaster.

After the execution of a SECPP2SDLCOMMAND event a reply is sent:

SECPP2SDLCOMMANDREPLY <#errors> <#warnings> <status>

The <#errors> and <#warnings> arguments tell the number of errors and warnings that occurred during the translation, and <status> is a text string with the same information in a more readable form.

Example 82 : Executing CPP2SDL from the PostMaster

A single PostMaster may be started with this command:

% sdt -noclients

Then CPP2SDL is started as a PostMaster client:

% cpp2sdl -post &

CPP2SDL is now waiting for requests to come from the PostMaster. By using for example the SERVERPC application, events can be sent to it.

% serverpc 58000 58101 "-rtti -ref input.h"

58000 is the tool id of CPP2SDL, and 58101 is the event id for the SECPP2SDLCOMMAND event. As a result the following reply event could for example be received:

SECPP2SDLCOMMANDREPLY 0 2 "0 errors and 2 warnings"

Finally, CPP2SDL is terminated using the SESTOP event (id 58303):

% serverpc 58000 58303


http://www.ibm.com/rational
Contents Index Previous Next