IBM
Contents Index Previous Next



Integrating Applications with SDL Simulators


An example of utilizing the functionality of the PostMaster is to connect a simulator generated by the SDL Suite to another application, typically a user interface (UI). The section Example of Use (UNIX only) presents a detailed description of such an example (UNIX only). The sections below concentrate on overall design issues and serves as an introduction to that example.

The communication between an SDL simulator and another application is handled by the PostMaster, and can be seen as occurring on two levels:

These two levels of communication are described further below.

Transferring SDL Signals

A simulator communicates with the world outside by sending and receiving SDL signals to/from its environment. For another application to communicate with the simulator, it must also be able to interpret those SDL signals, and to send and receive them. This includes mapping the information contained in the SDL signal (name and parameters) to components and actions in the UI, e.g. invoking a command or changing the contents of an output field.

To ensure successful communication with an SDL simulator, the SDL signal interface to the environment should be designed with regard to the connected applications. Decisions made when designing a UI can influence the design of the simulator interface, and vice versa. It is important to have a clearly defined signal interface to the applications that will communicate with the simulator.

Transferring PostMaster Messages

The PostMaster communicates with different tools by sending messages of a defined format. The SDL signals must therefore be transformed to PostMaster messages before they can be transferred between the tools. A few predefined PostMaster messages are available for the purpose of handling SDL signals.

Each tool designed to communicate by using SDL signals must have an interface to the PostMaster that handles the transformation to and from an appropriate message.

In the case of an SDL simulator, this interface is generated automatically. To invoke the transformation, so that SDL signals to and from the environment are transferred using the PostMaster, the monitor command Start-SDL-Env is to be used.

For other tools, the interface to the PostMaster must be implemented separately. The interface must use functions described later in this section to connect to the PostMaster, and to send and receive PostMaster messages containing SDL signals. This includes packing the information contained in the SDL signal (name and parameters) so that it can be sent using a PostMaster message, and unpacking the same information of a received message. See Input and Output of Data Types for more information on suitable data formats.

Example of Use (UNIX only)

This section describes an example of how to connect a user interface (UI) to an existing SDL simulator. The simulated system used in the example is the well-known Demon game, described in The Demon Game. All necessary code for the example is provided with the release.

The DemonGame simulator is connected through the PostMaster to a control program, consisting of two parts; an interface to the PostMaster and a user interface (see Figure 162).

The PostMaster interface establishes a connection to the PostMaster and communicates with the DemonGame simulator. Messages are sent via the PostMaster to the simulator where they are seen as SDL signals coming from the environment. Correspondingly, SDL signals to the environment are sent via the PostMaster as messages back to the PostMaster interface.

The UI facilitates sending and receiving of the SDL signals sent to and from the environment in the Demon game. A command-based UI (written in C) is implemented. However, the ideas are general and could be used if a graphical user interface is to be used. The UI must be able to forward the SDL signals Newgame, Endgame, Probe and Result, and to present the SDL signals Win, Lose and Score.

Figure 162 : System parts and their communication

Note:

The simulator and the control program have the same communication interface to the PostMaster. The simulator's interface to the PostMaster is generated automatically by the SDL Suite.

All C functions, C preprocessor symbols and PostMaster messages used in this example are described in PostMaster Reference.

The PostMaster Interface

All communication with the DemonGame simulator is handled by the interface to the PostMaster, a C program called env.c. This program contains the functions Init, Send_to_PM, Receive and Exit_PM, all of which must be called by the UI. Please note that the error handling in this program is very simple and does not comply with the design recommendations mentioned above.

Functions in env.c

Command-Based User Interface

The command-based UI prompts for and recognizes the commands "Newgame", "Endgame", "Probe", and "Result", corresponding to the SDL signals. When any of the SDL signals Score, Win or Lose are received, this information is printed. The command "Exit" exits the program.

The C program for the command-based UI is called command.c. It contains the functions:

Functions in command.c

The figures below show how the different functions and other parts in the DemonGame UI communicate with each other.

Figure 163 : Communication diagram

Running the Example

To be able to build and execute the example program, the software provided on the distribution media must first be properly installed.

Building the Tools

This section describes how to build the tools that will communicate via the PostMaster, i.e. the DemonGame simulator and the UI to the simulator.

The tools are provided in source code form and in binary form for the architecture on which you have purchased the SDL Suite.

The DemonGame Simulator

In the original implementation of DemonGame provided on the installation CD (in the examples/demongame directory), a design error has deliberately been introduced into the game definition. See Dynamic Errors for more information.

For the example program to execute correctly, this error must be corrected. New diagrams for the block GameBlock (gameblock.sbk) and the process Main (main.spr) are therefore provided, and are to be used to generate a new simulator. You can find the necessary files in the directory named sdt/examples/simulatorintegration.

  1. Either replace the above diagrams in the original DemonGame implementation, or copy the DemonGame diagrams to a new directory.
  2. Re-generate the simulator from the Organizer in the usual way.
  3. Change to the directory containing the files env.c, command.c, and makefile.
  4. Build the application with the UNIX make command. An executable named command is now created.
Executing a Session

This section describes how to start the communicating tools and initiate a session.

  1. Make sure you have the SDL Suite running, so that an instance of the PostMaster is started.
  2. Start the newly generated DemonGame simulator from the Organizer.
  3. Give the following commands to the simulator, preferably by including the provided command file init.sim.
    Start-SDL-Env
    Start handling of the SDL environment. See Start-SDL-Env.
    Set-Trace 1
    Restrict trace output to show only signals sent to and from the SDL environment.
    Go
    Start executing the simulation.
  4. Start the command-based UI (command) from the UNIX prompt.
  5. Send SDL signals from the UI by entering the signal name or pushing the corresponding button. (See the description earlier in this section.) Note the trace output in the simulator and the output in the UI.
  6. Exit by entering "exit" or using the File menu.

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