IBM
Contents Index Previous Next



PostMaster Reference


This section describes the external interface to the PostMaster, including messages to send and their format, contents of the configuration, and functions to call.

Note:

In order to promote a high throughput, it is strongly recommended that the PostMaster messages are consumed as soon as they are available.

PostMaster Messages

The PostMaster configuration defines a large number of messages that can be utilized in an SDL Suite or TTCN Suite system. A broad range of these messages are public, that is, they can be used externally. A description of these are found in The Public Interface.

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

The PostMaster can be configured either statically at start up or dynamically during runtime. When a dynamic configuration is performed, the services Add Tool or Add Tool Subscription is used. The PostMaster is configured statically using the PostMaster configuration file(s)

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 start-up the PostMaster reads an environment variable POSTPATH which is a list of directories separated by colons (on UNIX) or semicolons (in Windows). 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 the SDL Suite or the TTCN Suite is started.

It is not possible to use C preprocessor statements or symbols in the configuration file.

Caution!

The file post.cfd residing in $telelogic/sdt/bin and
$telelogic/itex/bin (on UNIX), or in the installation directory (in Windows), defines the existing tools in the environment and 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 SDL Suite and TTCN Suite by simply defining the POSTPATH variable with a directory holding the extended configuration.

File Contents and Syntax

The configuration is a list of tool identities. Each tool identity is bound to an executable, a subscription list of messages and optionally a limit of instances of that tool. Each tool in the file is described in the following way:

Tool <tool number>:<executable>:<instance limit>
<message number>;
<message number>;
...
Description

Adding Tools and Messages

To include new tools or add new messages, the configuration file must be edited. However, the tools and subscription lists existing in the original configuration must not be changed.

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/TTCN environment that does not need to be started from other tools by using the Start service.

  1. Select a tool number not conflicting with the ones already existing in the configuration, preferably a number greater than 100,000. The number chosen must be equally divisible by 1,000.
  2. Make a new tool description in the configuration, using the syntax described above.
  3. Define a new SET_ (IET_) symbol in the file sdt.h (itex.h) so that the tool number can be easily accessed in the code.

Example 27

#define SET_MYTOOL   110000

To add a new message, follow these steps:

  1. Decide upon a tool that the new message "belongs to" or "is defined by," which should not be one of the pre-defined tools in the original configuration.
  2. Define a new SE (IE) symbol in the file sdt.h (itex.h) as the tool symbol plus an ordinal number, not conflicting with any other message symbol.

Example 28

#define SEMYMESSAGE   SP_MESSAGE(SET_MYTOOL+1)

  1. Use the numeric value of the message symbol when adding the new message to a subscription list in the configuration.

Example 29

110000+1;

Environment Variables

The PostMaster recognizes a number of environment variables setting the context in which the PostMaster is to operate. They are read when the PostMaster starts.

PostMaster Environment Variables

The following environment variables are recognized by the PostMaster:

PostMaster Application Library Environment Variables

The following environment variables are recognized by the PostMaster application library. These environment variables are read in the SPInit function.

Functional Interface

Communication with the PostMaster is based on a small set of fundamental functions:

SPInit

initialization

SPExit

termination

SPBroadcast

output message, broadcast

SPSendToTool

output message, sent to a certain tool

SPSendToPid

output message, sent to a certain PId

SPRead

input message

SPFree

frees memory allocated by SPRead or SPFindActivePostMasters

SPConvert

translate a symbolic message to an id

SPErrorString

Error string conversion

SPRegisterPMCallback

Message notification (Windows only)

SPQuoteString

Quoting strings

SPUnquoteString

Unquoting strings

SPFindActivePostMasters

find all PostMasters

Every function returns a value denoting success or failure of the associated operation.

Calling Conventions

The PostMaster functions should be called in the following ways from the external tool:

Variables

The following variables are defined.

extern INT16 sperrno;

extern INT16 spPortNO; (on UNIX)
extern int spPortNO; (in Windows)

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.

On UNIX, spPortNO contains a descriptor to the port where incoming messages from the PostMaster are found. In Windows, spPortNO contains a process identifier associated with the current process. The state of the variable prior to the call of SPInit is undefined.

These variables are found in the file post.h.

Caution!

Windows only: When linking with the PostMaster's dynamically linked libraries (post.lib and post.dll), the environment variable USING_DLL must be defined before including post.h. Example:

#define USING_DLL

#include "post.h"

#undef USING_DLL

Error Codes

When a function returns SPERROR which indicates an error or an not expected result of the function. In this case sperrno is set to one of the following values.

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 memory (rare)

SPTOOLNOTFOUND

When sending to a tool, this tool is not found in PostMaster configuration list

SPINVALIDMESSAGE

Sending a message with a NULL parameter but specifying the length greater than 0.

SPBADMESSAGE

A not supported message was to be sent.

SPMANYPOSTMASTERS

Many PostMasters running. Could not decide which one to connect to. (Windows only)

SPOLDPOSTMASTER

Old PostMaster running. (Windows only)

Functional Description

The available PostMaster functions are described on the following pages. The descriptions use the following format.

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.

SPInit

int SPInit(int toolType,
           char * argv0,
           *SPMList list);

SPInit initiates a session and establishes a connection with the PostMaster. See Multiple PostMaster Instances for information on how to connect to a specific instance of the PostMaster.

Inparameters
Returns
Errors
SPNOPOSTMASTER
SPTIMEDOUT
SPALREADYCONNECTED
SPNOMEMORY
SPMANYPOSTMASTERS
SPOLDPOSTMASTER

SPExit

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.

Returns
Errors
SPNOCHANNEL
SPNOSESSION

SPSendToTool

int SPSendToTool(int tool,
                 int event,
                 void * data,
                 int size); 

SPSendToTool sends a message to the process of kind tool.

Inparameters
Returns
Errors
SPNOCHANNEL
SPNOSESSION
SPNOMEMORY
SPBADMESSAGE
SPINVALIDMESSAGE
SPTOOLNOTFOUND
SPBADMESSAGE
SPNOSUCHPID

SPSendToPid

int SPSendToPid(int pid,
                int event,
                void * data,
                int size); 

SPSendToPid sends a message to the process which has process id toPid.

Inparameters
Returns
Errors
SPNOCHANNEL
SPNOSESSION
SPNOMEMORY
SPBADMESSAGE
SPINVALIDMESSAGE
SPTOOLNOTFOUND
SPNOSUCHPID

SPBroadcast

int SPBroadcast(int event,
                void * data, 
                int size);

SPBroadcast sends a message to all processes that subscribes on the message type.

Inparameters
Returns
Errors
SPNOCHANNEL
SPNOSESSION
SPNOMEMORY
SPBADMESSAGE
SPINVALIDMESSAGE

SPRead

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 with SPFree when it is no longer needed.

Inparameters
Outparameters
Returns
Errors
SPNOCHANNEL
SPNOMESSAGE
SPNOSESSION
SPNOMEMORY

SPFree

void SPFree (void * ptr)

SPFree should be used to free the memory allocated by SPRead. This is necessary when different compilers with different memory management are used.

Inparameters
Returns

N/A.

SPErrorString

char * SPErrorString(int code);
               

Converts an error code into a textual string description of a tool or a message from the corresponding integer value.

Inparameters
Returns

An descriptive error string corresponding to the error code.

SPConvert

int SPConvert(char * str);

Converts a textual description of a tool or a message to the corresponding integer value as provided by the parameter list in SPInit.

Inparameters
Returns

An integer value for the tool or message. If no mapping is found, SPERROR is returned.

SPRegisterPMCallback

typedef void (* SP_PM_MessageCallback) (void);
void SPRegisterPMCallback (SP_PM_MessageCallback 
cb);
               

Windows only: Registers a callback function that gets called every time a new PostMaster message arrives. Registering this callback enables (32-bit) Windows applications to function correctly. Console applications need not use this function.

Inparameters
Returns

N/A.

SPQuoteString

int SPQuoteString(char *stringToQuote,
                  char *buffer,
                  int bufferLength,
                  int append)

SPQuoteString quotes a string. The following operations are performed:

The quoted string can later be unquoted with a call to SPUnquoteString.

Inparameters
Outparameters
Returns

SPUnquoteString

int SPUnquoteString(char *quotedString,
                    int inputLength,
                    char *buffer,
                    int bufferLength,
                    int position)

SPUnquoteString unquotes a string previously quoted with SPQuoteString, ignoring leading white-space characters. The following operations are performed:

Several concatenated quoted strings can be extracted with subsequent calls to this function by using the value returned in the position out parameter, see below.

Inparameters
Outparameters
Returns

SPFindActivePostMasters

int SPFindActivePostMaster (int *bufferPid, 
                            char** bufferText, 
                            int maxBufferlength);

Finds all PostMasters available for the application on the computer. Information retrieved is process id and a description in plain text.

Inparameters
Outparamters
Returns

Number of PostMasters found.

Java Interface

The file postmaster.java contains a java class that encapsulates the postmaster interface for java programmers. The class contains a few fundamental methods.

Init

initialization

SendToTool

output message, sent to a certain tool

SendToPid

output message, sent to a certain Pid

Broadcast

output message, broadcast

Read

read a message

Exit

termination

Init

int Init(int toolType);

SPInit initiates a session and establishes a connection with the PostMaster. See Multiple PostMaster Instances for information on how to connect to a specific instance of the PostMaster.

Inparameters
Returns

See functional description for the C interface

SendToTool

int SendToTool(int toolType, int message, 
	        String data);

SPSendToTool sends a message to the process of kind tool.

Inparameters
Returns

See functional description for the C interface

SendToPid

int SendToPid(int pId, int message, String data);

SPSendToPid sends a message to the process which has process id toPid.

Inparameters
Returns

See functional description for the C interface

Broadcast

int Broadcast(int message, String data);

SPBroadcast sends a message to all processes that subscribes on the message type.

Inparameters
Returns

See functional description for the C interface

Read

int Read(int timeOut);

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 data read by the last Read is copied to the Sender, Message and Data members of the class postmaster.

Inparameters
Returns

See functional description for the C interface

Exit

int Exit();

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.

Returns

See functional description for the C interface


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