![]() |
![]() |
![]() |
![]() |
![]() |
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:
- Sending and receiving SDL signals
- Sending and receiving PostMaster messages, containing the SDL signals
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.
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
- Init establishes a connection to the PostMaster by calling SPInit, identifying this tool as an SDL environment. The function broadcasts the message SESTARTNOTIFY to inform other tools that this tool has started. Finally it calls Init_UI, a function in the UI.
- Send_To_PM takes the name of an SDL signal as parameter and broadcasts this signal as an SESDLSIGNAL message to the simulator.
- Receive calls SPRead to wait for messages from the PostMaster, and acts suitably:
- If the message contains an SDL signal from the simulator (Score, Lose or Win), it is passed on to the UI by calling Send_To_UI, a function in the UI to present the receipt of the signal. It also returns true in these cases.
- If the message is a request to stop executing (SESTOP), it is accepted by calling Exit_UI, a function in the UI that in turn calls Exit_PM.
- If the message is SEOPFAILED, the PostMaster has failed to handle a message properly. You should then decode the message's parameters by calling
- Exit_PM broadcasts the message SESTOPNOTIFY and breaks the connection to the PostMaster by calling SPExit
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
- main calls Init in the PostMaster interface, prompts for input and examines the reading state of the file descriptors for the keyboard and the PostMaster message port. If input comes from the keyboard, GetInput is called and any valid SDL signal is sent by calling Send_To_PM in the PostMaster interface. If input comes from the message port, the message is read by calling Appl_Receive.
- GetInput reads the keyboard and compares the entered string with the available commands. If it is an SDL signal, the function returns true. If "exit" is entered, Exit_UI is called.
- Appl_Receive simply calls Receive in the PostMaster interface. It is included to make the functional interfaces equivalent for both user interfaces.
- Init_UI sets a file descriptor for the PostMaster message port and initializes unbuffered terminal output.
- Exit_UI calls Exit_PM in the PostMaster interface and exits the program.
- Send_To_UI prints the name of the received signal and any signal parameters on the terminal.
The figures below show how the different functions and other parts in the DemonGame UI communicate with each other.
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.
- Either replace the above diagrams in the original DemonGame implementation, or copy the DemonGame diagrams to a new directory.
- Re-generate the simulator from the Organizer in the usual way.
- Change to the directory containing the files env.c, command.c, and makefile.
- 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.
- Make sure you have the SDL Suite running, so that an instance of the PostMaster is started.
- Start the newly generated DemonGame simulator from the Organizer.
- 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.
- Start the command-based UI (command) from the UNIX prompt.
- 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.
- Exit by entering "exit" or using the File menu.
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |