![]() |
![]() |
![]() |
![]() |
![]() |
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.
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.
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.
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
- <tool number>
- <executable>
- is the name of the executable file associated with the tool. It is used by the PostMaster after receiving an SESTART message when a tool is to be started.
- A file path may prefix the filename of the executable in order to explicitly tell where to find the tool. In this case the complete file description (path + filename) should be surrounded by a pair of quotes (i.e. "/home/sdt/demo/demotool" (on UNIX) or "c:\sdt\demo\demotool" (in Windows)).
- <instance limit>
- <message number>
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.
- 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.
- Make a new tool description in the configuration, using the syntax described above.
- 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.
#define SET_MYTOOL 110000To add a new message, follow these steps:
- 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.
- 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.
#define SEMYMESSAGE SP_MESSAGE(SET_MYTOOL+1)
- Use the numeric value of the message symbol when adding the new message to a subscription list in the configuration.
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:
- POSTPORT
- UNIX only: Should be set to a valid TCP port number. Causes the PostMaster to try to listen to this port number for possible connections. Makes it possible to connect applications running on other hosts than the PostMaster is running on. Is used in combination with the client side environment variables POSTHOST and POSTPORT.
- POSTPATH
- POSTDEBUG
- If set, the PostMaster will log active tools and sent messages as an MSC log. The environment variable takes two optional parameters. The first tells the filename to put the log on. If the parameter is set to '-e' the log is put on stdout. The second parameter tells the log level. Normally only public messages are logged. But if set to a value > 2 all messages will be logged.
- If no parameters are submitted, the log will be stored on the file post.mpr
- See also Start MSC Log
- STARTTIMEOUT
- When the PostMaster executes its start service it assumes that the started client will connect, via SPInit, within a certain amount of time. This timeout (in seconds) sets the limit when the PostMaster considers the start having failed. Default is 60 seconds.
- If the SDL Suite and TTCN Suite tools environment is running on slow computer or on a network which is heavily loaded, start-up of a tool might fail due to this timeout. In such case, this environment variable should be increased to an appropriate value.
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.
- POSTHOST
- UNIX only: Should be set to a hostname, on which a PostMaster runs. This PostMaster should be started with the environment variable POSTPORT set.
- POSTPORT
- UNIX only: Should be set to a valid TCP port which is allocated to a PostMaster. Corresponds to POSTPORT set for the PostMaster.
- POSTPID
- This environment variable is only of interest if multiple PostMasters are simultaneously active. If it is desired to make a connection to one particular PostMaster, this environment variable should be set to the process id corresponding to that PostMaster.
- If only one PostMaster is active, the application library automatically finds the PostMaster.
- 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.
Functional Interface
Communication with the PostMaster is based on a small set of fundamental functions:
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:
- The first thing to do is to initiate the connection with the PostMaster itself by calling SPInit. This is preferably done early in the main program. This initiation is private to the client and the PostMaster.
- When having successfully called SPInit, the tool should listen to the PostMaster message port and read the incoming messages by SPRead. The tool should then act upon the messages it subscribes on.
- If so desired, the tool should send messages by calling SPSendToTool, SPSendToPid or SPBroadcast.
- When the tool decides to terminate, it should broadcast the standard message SESTOPNOTIFY by calling SPBroadcast. Then it should disconnect from the PostMaster by calling SPExit.
- Every call to a PostMaster function should check the return value and act properly if an error is detected.
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.
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.
SPNOSESSIONThe function SPInit has not been called successfully
SPALREADYCONNECTEDWhen calling SPInit more than once without disconnecting
SPNOPOSTMASTER SPNOCHANNEL SPNOMESSAGENo message available when trying to read by polling or after a timeout.
SPTIMEDOUT SPNOSUCHPID SPNOMEMORY SPTOOLNOTFOUNDWhen sending to a tool, this tool is not found in PostMaster configuration list
SPINVALIDMESSAGESending a message with a NULL parameter but specifying the length greater than 0.
SPBADMESSAGE SPMANYPOSTMASTERSMany PostMasters running. Could not decide which one to connect to. (Windows only)
SPOLDPOSTMASTERFunctional 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
- toolType
- The tool number identifies the tool and should be a value available in the PostMasters subscription list. For tools acting as an SDL/TTCN environment, it should be set to SET_SDLENV. See Run-Time Considerations for more information.
- argv0
- list
- Defines a list of predefined messages allowed to send. It also provides a set of mappings between textual strings and integer values for tools and messages. Normally the list provided in sdt.h (itex.h) is used. This list is later used by the function SPConvert, which translates between a textual string and the corresponding identifier.
Returns
- >0
- On UNIX, the PId of the calling process. Normally this PId corresponds to an UNIX PId. But if the PostMaster is started with the environment variable POSTPORT set, the PostMaster decides what PId value each client should get. In this case the numbering scheme gives the first started client 1, the next 2 and so on.
- In Windows, an identifier ("PId") which is used internally by the PostMaster in order to uniquely identify the calling process.
- This value could be used when sending messages and in comparisons with PIds contained in received messages.
- SPERROR
Errors
SPNOPOSTMASTERSPTIMEDOUTSPALREADYCONNECTEDSPNOMEMORYSPMANYPOSTMASTERSSPOLDPOSTMASTERSPExit
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
SPNOCHANNELSPNOSESSIONSPSendToTool
int SPSendToTool(int tool,int event,void * data,int size);SPSendToTool sends a message to the process of kind tool.
Inparameters
Returns
Errors
SPNOCHANNELSPNOSESSIONSPNOMEMORYSPBADMESSAGESPINVALIDMESSAGESPTOOLNOTFOUNDSPBADMESSAGESPNOSUCHPIDSPSendToPid
int SPSendToPid(int pid,int event,void * data,int size);SPSendToPid sends a message to the process which has process id toPid.
Inparameters
- pid
- PId of the message's receiver. If the specified PId does not exist, an SEOPFAILED message or a service reply is sent by the PostMaster.
- event
- data
- size
Returns
Errors
SPNOCHANNELSPNOSESSIONSPNOMEMORYSPBADMESSAGESPINVALIDMESSAGESPTOOLNOTFOUNDSPNOSUCHPIDSPBroadcast
int SPBroadcast(int event,void * data,int size);SPBroadcast sends a message to all processes that subscribes on the message type.
Inparameters
Returns
Errors
SPNOCHANNELSPNOSESSIONSPNOMEMORYSPBADMESSAGESPINVALIDMESSAGESPRead
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
- timeOut
- Maximum amount of time (in milliseconds) that the function waits for a message. If a message has not arrived when timeOut expires, the function returns with return value SPERROR and sperrno is set to SPNOMESSAGE. If a message arrives, the function reads the message and returns immediately. If the desired behavior is to wait until a message arrives, which could mean forever, timeOut should be set to SPWAITFOREVER.
Outparameters
Returns
Errors
SPNOCHANNELSPNOMESSAGESPNOSESSIONSPNOMEMORYSPFree
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
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
- str
- Textual description of the tool or message. The list provided in SPInit is used when searching for a mapping.
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
SPQuoteString
int SPQuoteString(char *stringToQuote,char *buffer,int bufferLength,int append)SPQuoteString quotes a string. The following operations are performed:
- A quote is added to the beginning and end of the string.
- All quotes and backslashes in the string are escaped, i.e. a backslash character is added before them.
The quoted string can later be unquoted with a call to SPUnquoteString.
Inparameters
- stringToQuote
- bufferLength
- The size of the buffer (see the outparameter buffer below).
- append
- If the value of append is non-zero, buffer is supposed to already contain a null-terminated string. The result of the quoting operation will be appended to this string at the end.
- If several quoted strings are concatenated, they can be extracted and unquoted one at a time with calls to the SPUnquoteString function.
Outparameters
- buffer
- Pointer to a buffer where the resulting, quoted string will be returned. The buffer must be large enough to contain all the characters of the quoted string plus a trailing null character. The maximum buffer size needed can be quoted with the following formula:
- maximum buffer size = unquoted string size * 2 + 3
- This includes space for escaping every character in the string, plus three bytes for quotes and null character. A larger buffer might of course be needed when appending (see append above).
- The size of the buffer is given in bufferLength. If the quoted string does not fit in the buffer, the function will fail and return zero (further explained in the next section).
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:
- Any white-space characters in the beginning of the string are ignored. If the string is empty or contains only white-space characters, the function call fails and returns zero (see Returns).
- If the first character after white-spaces is a quote, the function assumes that this quote starts a string quoted with SPQuoteString. In this quoted string, backslashes escape the following character. The string is ended with a non-escaped quote.
- If the first character after white-spaces is not a quote, the function will simply extract and return a substring up to but not including the next white-space character. If no further white-space characters are found, the rest of the string is returned. Backslashes and quotes have no special meaning when unquoting strings in this way.
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
- quotedString
- Pointer to a string containing the string previously quoted with SPQuoteString. The string should either be null-terminated or inputLength below should have a meaningful value.
- inputLength
- bufferLength
- The size of the buffer (see the outparameter buffer below).
Outparameters
- buffer
- A pointer to a buffer where the unquoted string will be returned. The buffer must be large enough to contain the resulting, unquoted string, including null character. A buffer one character larger than inputLength will always suffice. If the buffer is too small, the function call will fail and return zero (see Returns). The size of the buffer is given in bufferLength.
- buffer can also be null, in which case no unquoting will be performed. The value of position can still be interesting, though.
- position
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
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 SendToTool SendToPid Broadcast Read ExitInit
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
- pid
- PId of the message's receiver. If the specified PId does not exist, an SEOPFAILED message or a service reply is sent by the PostMaster.
- message
- data
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
- timeOut
- Maximum amount of time (in milliseconds) that the function waits for a message. If a message has not arrived when timeOut expires, the function returns with return value SPERROR and sperrno is set to SPNOMESSAGE. If a message arrives, the function reads the message and returns immediately. If the desired behavior is to wait until a message arrives, which could mean forever, timeOut should be set to SPWAITFOREVER.
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
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |