IBM
Contents Index Previous Next



Introduction


The first example shows a simple application, the Service Encapsulator, by which it is possible to request SDL Suite or TTCN Suite tools services from the Operating Systems command line. The example shows how to use the PostMaster interface.

The second example uses the Service Encapsulator and shows the usage of some SDL Suite Services. Since the "DOS" command prompt is rather weak in its scripting capabilities, no example script file is included for Windows in this example.

The third example uses the Service Encapsulator and shows the usage of some TTCN Suite Services.

The final example exemplifies how to integrate an SDL simulator and a separate user interface (UNIX only). How to design such a user interface is described in a detailed example. It is assumed that the reader has experience of creating and running SDL simulators.

The Service Encapsulator

Introduction to the Service Encapsulator

This section shows an application, the Service Encapsulator, implementing a command line service request encapsulation. That is, services as made available by the Public Interface, could be obtained from the command line.

The purpose of this example is to show:

The application is general in the sense that it does not require any SDL Suite or TTCN Suite tool to be running (only the PostMaster is required to be running), but in this context it exemplifies a number of services.

From the outside world the application behaves like a tool providing remote procedure call functionality. That is, when the service is requested, the application synchronously waits for the service reply, before returning (the application exits).

The example is found in the SDL Suite and TTCN Suite distribution in the subdirectory examples and then public_interface.

The Service Encapsulator is also available as a tool in the SDL Suite and TTCN Suite environment, see The Service Encapsulator.

Design

In this section is a few important aspects in the design and implementation of the Service Encapsulator given. The source file is named serverpc.c and the executable is named serverpc.

The tool connects to the PostMaster by issuing:

SPInit(SET_EXTERN, argv[0], spMList) (in SDL Suite)
SPInit(IET_EXTERN, argv[0], ipMList) (in TTCN Suite)

The first parameter gives the type of application. In this case SET_EXTERN or IET_EXTERN is used. This application type is a predefined tool type for external applications connecting to SDL Suite and TTCN Suite. The variable spMList or ipMList gives the possibility to convert between textual (symbolic) values and integers.

If SPInit succeeds, SPInit broadcasts a SESTARTNOTIFY, indicating to all other tools in the environment that an additional tool is connected.

 if ((tool=atoi(argv[1])) == 0 )
   tool = SPConvert(argv[1]);

If the parameter <tool> was given textually, the function SPConvert converts it to the corresponding integer value. If a mapping cannot be found, -1 is returned. This is an error and will be detected in the SPSendToTool function, see below.

if ((sendEvent=atoi(argv[2])) == 0 )
   sendEvent = SPConvert(argv[2]);

Allocating memory for the message parameter is done as follows:

for (i=3;i<argc;i++) {
  p = realloc(p, strlen(p) + strlen(argv[i]) + 2);
  if (strlen(p)>0)
    p = strcat(p, " ");
  p = strcat(p, argv[i]);
}

The handleescape function allows carriage return "\n", "\r" and "\0" to be used when sending messages:

 p = handleescape(p);

A normal service request is issued by:

status=SPSendToTool(tool, sendEvent, p, strlen(p)+1;

The last parameter tells the length of the parameter provided by argv[3] and must be extended by 1 to include the terminating \0 character.

Now the service request message is sent to the PostMaster which forwards it to the server application. If not busy, the Service application starts to process the service request and when finished it replies with a service reply message to the issues. However, during the processing other messages can be sent or broadcast to the Service Encapsulator (the service issuer). Therefor we must enter a loop where we stay until the reply message is received. Other kind of messages are dropped.

do {
   if (( status=SPRead(SPWAITFOREVER, &pid,
         &replyEvent,(void*)&replyMessage, &len))!=0 
)
      OnError("Error reading from postmaster: ");
} while ( ! SP_MATCHREPLY(sendEvent, replyEvent) );

The function SPRead reads a message form the PostMaster. The first parameter, the timeout, could be set to wait indefinitely until a message arrives, using the value SPWAITFOREVER.

This simple application has a drawback: if something unexpectedly happens to the server, it might be that no service reply will be sent which means that we block in SPRead forever. The behavior could be enhanced by setting a timeout, and when the timeout expires, check the state of the server (Use the PostMaster service Get Tool Pid).

If the service readattribute was issued, special care must be taken to handle the answer, since it contains binary data. The length of the data part ends the replyMessage. The end is indicated by an ASCII 0. The data part immediately follows the ASCII 0 character and might contain non-ASCII characters. Our printout assumes ASCII data.

if ( sendEvent == SEREADATTRIBUTE ) {
   printf("%s", replyMessage+1);
   printf("%s\n", replyMessage+ strlen(replyMessage)   
          +1);
}

The macro SP_MATCHREPLY compares the issued service request message and the reply message and returns true if the correct received message was the correct service reply message.

The service reply is then printed on standard output. The following prints the service reply data:

int i;
for( i=2;i<len;i++ )
  putchar(replyMessage[i]);
putchar('\n');

Counting starts at position 2, omitting the service reply status.

free (replyMessage);

replyMessage was dynamically allocated using malloc in SPRead, so it must be freed.

Before terminating the application, notify all other applications in the environment that it is going to break its connection to the PostMaster

SPBroadcast(SESTOPNOTIFY, NULL, 0);

Finally we terminate the PostMaster connection by calling:

SPExit ();

Generating the Application for the SDL Suite

To generate the application do the following:

  1. Change the current directory to the sub directory containing the example:
    On UNIX: cd <Installation 
    Directory>/examples/public_interface
    
    
    
    In Windows: cd <Installation 
    Directory>\examples\public_interface
    
    
    
  2. Set the environment variable telelogic to point to the right directory. This is platform dependent.
    On UNIX: setenv telelogic <Installation Directory>
    
    
    
    In Windows: set telelogic=<Installation Directory>
    
    
    
  3. Generate the application:
    On Solaris: make -f Makefile.solaris
    In Windows using Microsoft: nmake /f Makefile.msvc

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