Table of ContentsTable of Contents 
Previous Chapter --------------------------------------------------------------------- Caution! The SDT PostMaster was originally designed and implemented for integrating tools in the SDT environment. Our experience is that the PostMaster is also suitable for integrating external tools and appli cations with SDT applications; one application area is for instance quick prototyping. However, Telelogic does not support using the PostMaster as a com munication mechanism between real-time applications, in a run- time environment. ---------------------------------------------------------------------The PostMaster is the mechanism used for communication between the different tools in SDT. A C program generated by SDT can also take advantage of this communication mechanism. It can communicate with any application connected to the PostMaster that send messages according to a defined format. This makes it possible for an SDT simulator to communicate with, for instance, a User Interface process generated by
The PostMaster provides the following functionality:
Figure 562 illustrates some of the PostMaster concepts. The PostMaster maintains a list of which messages each tool subscribes to. Each tool has a PostMaster part for sending and receiving messages. In the figure, tool F broadcasts a message, i.e. the message is sent to the PostMaster. The subscription lists of tool A and C (but not the lists of B and F) contains the message type. Accordingly the PostMaster broadcasts the message to tool A and C.
Figure 562 : Example of a PostMaster broadcast. ----- (fig) -----The PostMaster configuration is a file that informs the PostMaster about what tools and messages exist in the current context, i.e. it contains the message subscription lists. To include new tools or add new messages, the configuration must be edited.
For detailed information on the configuration, see "The PostMaster Configuration" on page 2485.
For each application a UNIX socket is created. The usable size of this socket is implementation dependent. On platforms where this size is limited, the PostMaster maintains internal queues to overcome this problem. However, under exceptional circumstances, even these queues may be exhausted. To avoid this problem an application should always be prepared to consume its input from the PostMaster, or, if that is not possible, frequently check for incoming messages.
-------------------------------------------------------------------- Note: In order to promote a high throughput and avoiding buffer overflow, it is therefore strongly recommended that the PostMaster messages are consumed as soon as they are available. If an overflow occurs, the result is unpredictable. --------------------------------------------------------------------
All messages contain information about the identity of the sender, the time it was sent, the message type, and the size of an optional data part.
The optional data part can be seen as parameters to the message and is not interpreted by the PostMaster.
------------------------------------------------------------------------- Note: It is the responsibility of the tools using the PostMaster to define the format of the data part and to interpret it correctly. -------------------------------------------------------------------------
The PostMaster configuration file(s) informs the PostMaster about what tools and messages exist in the current context. These files are often referred to as simply the configuration.
At startup the postmaster reads an environment variable POSTPATH which is a colon `:' separated list of directories. In these directories, the PostMaster searches for configuration files.
Such files should be named post.cfd and are read by the PostMaster whenever it is invoked, for instance when SDT is started.
It is not possible to use C preprocessor statements or symbols in the configuration file.
------------------------------------------------------------------ Caution! The file post.cfd residing in $sdtbin that defines the existing tools in SDT must not be edited; otherwise unpredictable behavior may occur. ------------------------------------------------------------------It is possible to have local configurations which extends the standard postmaster configuration set up by SDT, by simply defining the POSTPATH variable with a directory holding the extended configuration.
Tool <tool number>:<executable>:<instance limit>
<message number>;
<message number>;
...
To include a new tool, follow the steps below. Note that it is not required to include a new tool in the configuration if it only serves as an SDL environment that does not need to be started from other tools by using the Start service.
Example 254 #define SET_MYTOOL 110000To add a new message, follow these steps:
Example 255 #define SEMYMESSAGE SP_MESSAGE(SET_MYTOOL+1)
Example 256 50000+1;
If more than one PostMaster is running and this environment variable is not set, a connection is made to the PostMaster instance having the highest process id value.
-------------------------------------------------------- SPInit -- initialization SPExit -- termination SPBroadcast -- output message, broadcasted SPSendToTool -- output message, sent to a certain tool SPSendToPid -- output message, sent to a certain pid SPRead -- input message SP -- translate a symbolic message to an id SPErrorString -- Error string conversion --------------------------------------------------------Every function returns a value denoting success or failure of the associated operation.
extern INT16 sperrno; extern INT16 spPortNO;sperrno contains an error code when a call to a PostMaster function failed. The error codes are defined in sdt.h and should be self-explanatory.
spPortNO contains a descriptor to the port where incoming messages from the PostMaster are found. The state of the variable prior to the call of SPInit is undefined.
These variables are found in the file post.h.
--------------------------------------------------------------- Error Code Explanation --------------------------------------------------------------- SPNOSESSION The function SPInit has not been called successfully SPALREADYCONNECTED When calling SPInit more than once without disconnecting SPNOPOSTMASTER No postmaster could be found when trying to connect SPNOCHANNEL The contact with the postmaster is lost. SPNOMESSAGE No message available when trying to read by polling or after a timeout. SPTIMEDOUT The connection to the PostMaster timed out. SPNOSUCHPID Sending to a Pid with a non positive value (<=0) SPNOMEMORY Cannot allocate anymore dynamic mem ory (rare) SPTOOLNOTFOUND When sending to a tool, this tool is not found in postmaster configuration list SPINVALIDMESSAGE Sending a message with a NULL parame ter but specifying the length greater than 0. SPBADMESSAGE A not supported message was to be sent. ---------------------------------------------------------------
First, the function declaration is shown, including data types of parameters, followed by a short explanation of what the function does.
After that, in- and out parameters are described, together with possible return values and error codes.
int SPInit(int toolType,
*SPMList list);
SPInit initiates a session and establishes a connection with the PostMaster. See "Multiple PostMaster Instances" on page 2498 for information on how to connect to a specific instance of the PostMaster.
SPNOPOSTMASTER SPTIMEDOUT SPALREADYCONNECTED SPNOMEMORY
int SPExit(void);SPExit exits a session and disconnects the connection with the PostMaster. Subsequent calls to PostMaster functions will return the error code SPNOSESSION until a new SPInit is performed.
SPNOCHANNEL SPNOSESSION
int SPSendToTool(int tool,
int event,
void * data,
int size);
SPSendToTool sends a message to the process of kind type.
SPNOCHANNEL SPNOSESSION SPNOMEMORY SPBADMESSAGE SPINVALIDMESSAGE SPTOOLNOTFOUND SPBADMESSAGE SPNOSUCHPID
int SPSendToPid(int pid,
int event,
void * data,
int size);
SPSendToPid sends a message to the process which has process id toPid.
SPNOCHANNEL SPNOSESSION SPNOMEMORY SPBADMESSAGE SPINVALIDMESSAGE SPTOOLNOTFOUND SPNOSUCHPID
int SPBroadcast(int event,
void * data,
int size);
SPBroadcast sends a message to all processes that subscribes on the message type.
SPNOCHANNEL SPNOSESSION SPNOMEMORY SPBADMESSAGE SPINVALIDMESSAGE
int SPRead(int timeOut
int pid,
int *message,
void ** data,
int * len);
SPRead reads a message from the queue of unread messages that the PostMaster has sent. When the message is read, it is also consumed, i.e. removed from the queue. The function allocates the necessary amount of memory needed for the data component in the message. The application using this function is responsible for freeing the allocated memory when it is no longer needed.
SPNOCHANNEL SPNOMESSAGE SPNOSESSION SPNOMEMORY
char * SPErrorString(int code);
Converts an error code into a textual string textual description of a tool or a message to the corresponding integer value.
int SP(char * str);Converts a textual description of a tool or a message to the corresponding integer value as provided by the variable list in SPInit.
-------------------------------------------------------------------- Note: The PostMaster must be started first, but the communicating tools may be started in any order. An SDT simulator must also execute the commands StartSDTEnv and Go before communication with an other tool can start. --------------------------------------------------------------------
The DemonGame simulator is preferably started from SDT, thus giving access to all simulation features. It can also be started directly from the UNIX prompt with the command
DemonGame.sct -post. (Without the parameter, the simulator runs stand-alone, which is not desired in this case.) Starting the simulator this way restricts the possibilities of the simulation since there is no connection to the SDT tools. For instance, graphical trace is disabled.
The UI is preferably started directly from the UNIX prompt. It can also be started from the DemonGame simulator with the command StartUI, but this requires that the executable is named sdtenv. This is the name specified in the configuration for tool number 27000.
The DemonGame simulator must also be started directly from the UNIX prompt, as described above.
---------------------------------------------------------------- Note: If activating the PostMaster this way, the environment variable POSTPATH must be set to include the directory where the SDT exe cutables resides, typically $sdtbin. ----------------------------------------------------------------The UI can be started in the same way as when SDT is running (see above). It can also be started indirectly when starting the PostMaster by using the UNIX command $sdtbin/sdtpm -clients 27000 &. This requires that the executable is named sdtenv, the name specified in the configuration for tool number 27000.
------------------------------------------------------------------- Note: A tool communicating through the PostMaster can also be started from another tool by using the SESTART message. This requires that the tool to be started is specified in the configuration. -------------------------------------------------------------------
Postmaster cannot connect SDT2 tool:<tool> with pid: <pid>on standard output, if externally started, or as a service reply, if started via the start service, and the connection is aborted.
By default, the function SPInit looks for the PostMaster instance with the highest process id (PId) number and connects to it. To connect to another PostMaster instance, you can set the environment variable
sdtpostpid to the PId number of the desired PostMaster. If this variable is set, SPInit connects to the PostMaster instance with that PId number.
The user can extend the normal SDT configuration by defining the POSTPATH variable to a directory containing an extended configuration. When SDT is started normally, via its' start script, the directory containing the SDT binaries are put as the first directory in the POSTPATH variable.
The same search order is applied when the start service is used. The supplied tool number is matched against the name of an executable in the configuration, which is then searched for as above.
This page intentionally left blank
Next Chapter