IBM
Contents Index Previous Next



General Concepts


Introduction

Significant steps have been made to increase the openness of SDL Suite and TTCN Suite tools by the introduction of the Public Interface. Openness is provided both in terms of diverse ways of controlling the tools and the way data handled by the tools is made visible.

Application Areas

Two different kinds of usage of the Public Interface could be foreseen:

The Public Interface

The public interface has been made possible due to the modularity of the tools and thanks to the well defined interfaces by which the tools have been built.

The public interface is made available using two different mechanisms.

The PostMaster

The PostMaster forms an integral mechanism to integrate tools in the SDL Suite and TTCN Suite tools environment (a reference to the PostMaster is provided in The PostMaster).

It is also used as a low level mechanism to physically integrate SDL Suite and TTCN Suite tools with external tools. The PostMaster provides three basic facilities:

These facilities are used to implement the concepts provided by the SDL Suite and the TTCN Suite tools services. These are built up of Services and Notifications. A special case of service is Communication with SDL Simulators.

It is important to note that the interface provided could be extended for client-client usage outside SDL Suite and TTCN Suite as long as the conventions described in this document are followed.

Services

Services provides access to functionality within the SDL Suite and the TTCN Suite. Such functions could be used by an external tool to exercise control, to integrate SDL Suite or TTCN Suite with external tools or have SDL Suite and TTCN Suite take part in a larger environment.

Services adopts the client-server concept where a request is sent by a client to a server, which returns with a reply. Service request and service reply take both advantage of message sending from one tool to another.

Notifications

These are broadcast messages which are spontaneously emitted when a significant event takes place in SDL Suite or TTCN Suite. Often these notifications are caused by a service being successfully processed.

Communication with SDL Simulators

When external applications are to communicate with SDL Simulators, the message SESDLSIGNAL is used. It is asynchronously sent/broadcaster into the system. All simulators subscribes on this message. As a parameter to this message is the receiver (in the context of SDL) provided.

Overview of Available Services

The following services are provided for external usage. A service is normally supported by a specific tool or a few of the tools. Some of the services correspond to a menu choice or an operation performed by a user using the tools's graphical interface.

In the following services, the Configuration Services and the System File Services are applicable to SDL Suite and TTCN Suite, and the TTCN Suite Services are only applicable to the TTCN Suite. All other services are only applicable to SDL Suite.

Configuration Services

Service Servers Graphical correspondence

Start Tool

PostMaster

Start a new tool

Stop Tool

All tools

Exit menu choice

Get Tool Type

PostMaster

N/A

Get Tool Pid

PostMaster

N/A

Add Tool

PostMaster

N/A

Add Tool Subscription

PostMaster

N/A

System File Services

Service Servers Graphical correspondence

List System Files

Organizer

N/A

New System

Organizer

New quick button

Open System

Organizer

Open quick button

Save System

Organizer

Save quick button

Add Existing

Organizer

Add Existing menu choice

Link File Services

Service Servers Graphical correspondence

Add Local Link File

Organizer

N/A

Merge Local Link File

Organizer

N/A

TTCN Suite Services

Service Servers Graphical correspondence

Convert to GR

ITEX

N/A

Opened Documents

ITEX

N/A

Fetch Buffer Identifier Given the Database

ITEX

N/A

Fetch Buffer Identifier Given MP File Path

ITEX

N/A

Convert to MP

ITEX

N/A

Convert Selection to MP

ITEX

N/A

Merge Document

ITEX

N/A

Analyze Document

ITEX

N/A

Close Document

ITEX

N/A

Save Document

ITEX

N/A

Selector

ITEX

N/A

SelectAll

ITEX

N/A

DeselectAll

ITEX

N/A

IsSelected

ITEX

N/A

Get Modify Time

ITEX

N/A

Get Path

ITEX

N/A

Get MP Path

ITEX

N/A

Find Table

ITEX

N/A

Close Table

ITEX

N/A

Get Table State

ITEX

N/A

Get Row Number

ITEX

N/A

Select Row

ITEX

N/A

Clear Selection

ITEX

N/A

Rows Selected

ITEX

N/A

Menu Manipulation Services

Service Servers Graphical correspondence

Add Menu

Organizer

SDLE

MSCE

OME

TE

Coverage Viewer

Index Viewer

Type Viewer

Tree Viewer

File Viewer

Preference Manager

SimUI/ExpUI

N/A

Delete Menu

As for Add Menu above.

N/A

Clear Menu

As above.

N/A

Add Item to Menu

As above.

N/A

Add Item to Menu - Organizer

Organizer

N/A

Add Item to Menu - Text Editor

TE

N/A

Add Item to Menu - Graphical Editors

SDLE

MSCE

OME

N/A

Logging Services

Service Servers Graphical correspondence

Start MSC Log

PostMaster

N/A

Stop MSC Log

PostMaster

N/A

SDT Reference Services

Service Servers Graphical correspondence

Show Source

Organizer

Show source menu choice

Obtain GR Reference

SDLE

MSCE

OME

N/A

Editor - Diagram Services

Service Servers Graphical correspondence

Load Diagram

SDLE

MSCE

OME

TE

Open menu choice

Unload Diagram

SDLE

MSCE

OME

TE

Close menu choice

Show Diagram

SDLE

MSCE

OME

TE

Diagrams menu

Save Diagram

SDLE

MSCE

OME

TE

Save menu choice

Create SDL Diagram

SDLE

New menu choice

Create MSC Diagram

MSCE

New menu choice

Create OM Diagram

OME

New menu choice

Create Text Diagram

TE

New menu choice

Editor - Object Services

Service Servers Graphical correspondence

Select Object

SDLE

MSCE

OME

Selecting an object

Show Object

SDLE

MSCE

OME

Selecting an object

Insert SDL Object

SDLE

Select object in symbol menu

Insert MSC Object

MSCE

Select object in symbol menu

Remove Object

SDLE

MSCE

OME

Clear menu choice

Get Object Text

SDLE

MSCE

OME

N/A

Editor - Object Attribute Services

Service Servers Graphical correspondence

Display Key

SDLE

MSCE

OME

N/A

List Key

SDLE

MSCE

OME

N/A

Create Attribute

SDLE

MSCE

OME

N/A

Update Attribute

SDLE

MSCE

OME

N/A

Read Attribute

SDLE

MSCE

OME

N/A

Delete Attribute

SDLE

MSCE

OME

N/A

Information Server Services

Service Servers Graphical correspondence

Load Definition File

Information Server

N/A

SDL Editor Services

Service Servers Graphical correspondence

GRPR

SDLE

N/A

Tidy Up

SDLE

Tidy Up menu choice

SC Editor Services

Service Servers Graphical correspondence

Get Diagram Info

OME

N/A

MSC Editor Services

Service Servers Graphical correspondence

MSC GRPR

MSCE

Generate MSC PR menu choice

HMSC Editor Services

Service Servers Graphical correspondence

HMSC GRPR

MSCE

Generate MSC PR menu choice

CIF Services

Service Servers Graphical correspondence

Create SDL Diagram

SDLE

N/A

Create SDL Page

SDLE

N/A

Insert SDL Object

SDLE

N/A

Create OM Diagram

OME

N/A

Create OM Page

OME

N/A

Insert OM Object

OME

N/A

Text Editor Services

Service Servers Graphical correspondence

Show Position

TE

N/A

Select Text

TE

N/A

Client Interface

A client which would like to make an integration using these facilities should consult the following interface:

External Client types

Clients connecting to the PostMaster must be known by the PostMaster. This can be accomplished in a number of ways:

  1. By defining a configuration file containing the extended configuration, name this file to post.cfd and to set the environment variable POSTPATH to include the directory where the file is stored.
    A change in this file is kind of static nature, since the configuration files are read every time the PostMaster is started.
  2. By modifying the configuration dynamically. Requires a PostMaster to be running. The PostMaster provides services for dynamically changing a configuration, adding tools and adding subscriptions. This is easily done via a script and does only affect the current session.

New tool types or message types added to the PostMaster tool and subscription list should be set in a range not conflicting with SDL Suite and TTCN Suite. New tools and messages should use values above 100000. Exact numbering should follow the scheme used by the SDL Suite and the TTCN Suite:

Item Description

Tools

Use values in steps of 1000

Service Request

Base the value on the tool providing the service and add local base of 100. Then sequentially number the services

Service Reply

Base the value on the corresponding service request and add 100.

Notifications

Base the value on the tool broadcasting the notification and add the messages sequentially.

Message Based Services

Introduction

Using a message based service requires the client to be connected to the PostMaster. To invoke a service, the application sends a service request message to the tool providing the service. A service request message will normally cause a reply message to be sent to the client. An exception is if the server unexpectedly terminates while processing the service.

The client could choose whether to wait for the reply message (emulating a remote procedure call) or to continue working and intercept the reply message via a callback routine.

The client does not need to subscribe on service request messages or service reply messages. However the client itself must be present in the configuration list.

A server can only process one service at time. If additional services are requested from that particular server when being occupied processing the first service, the server is said to be busy and a service error reply is returned to the requester. Other kinds of messages received by server during the processing of a service request are queued up and will be processed as soon as the service has completed.

Service Request

A service request normally takes advantage of the SPSendToTool function. If more than one instance of a tool is active the function SPSendToPid will be more appropriate. The reply is fetched with the SPRead function. The client must however verify that the read message is the reply message. The macro SP_MATCHREPLY could be used to determine whether the received message is the desired reply.

Service Reply

The first parameter in the service reply informs about the result of the service request. The following codes are used:

Status Code Value Description
OK

0

The service was successfully processed. Optional parameters are provided in the reply message.

Busy

1

The server is busy and cannot process the service. The service request is aborted. An additional message might be provided.

ErrorString

2

The server failed to process the service. The remaining parts of the message contain an error message.

ErrorCode

3

The server failed to process the service, the next parameter in the service reply is a code indicating the error.

In the detailed description of each service, the reply format is only specified for the normal case returning OK. For services replying errors in the ErrorString format, the text may be context sensitive and only major error causes are specified.

Error Handling

Error handling takes place at two different levels.

  1. The service request failed to be issued.
    Service Request message couldn't be sent. In such case the SPSendToTool, SPSendToPid returns false and the variable sperrno indicates the error. It also means that a service reply message will not be sent.
  2. While processing the service.
    In this case the service request reaches the server but cannot be processed or the processing of the service fails. In such a case, an error code is provided in the service reply message. The error is either provided as a code or as explanatory text.

How to decode the service reply is described in the section below.

Common Errors

These errors are common to all services. They all use the ErrorString format. Where applicable, an additional explanatory text is added to the strings below:

Bad parameters
Server busy
Service not supported
Server locked
SDT Reference Errors

When a service request refers to an SDT reference, the following errors may occur:

Reference must contain paranthesis
Reference must start with #SDTREF
Invalid reference
Garbage after reference
Embedded value not terminated
Illegal value in paranthesis after token <token-nr>
Junk after embedded value
Incomplete reference lacking trailing paranthesis
Unsupported reference type <token>
Symbol must be integer >= 0
Malformed coordinate

For a reference to the syntax of references, see SDT References.

Notifications

Certain services will broadcast notifications as the service is processed in order to inform other participants than the service issuer that an operation has been performed by the server or that the state of the server has changed.

Message Parameters

Normally a message (a service request, a service reply, a notification or other) uses one or more parameters. Generally all such parameters are stored in a PostMaster message's data part.

The following parameter types are used:

Type Description
integer

32 bit integer in ASCII form.

bool

Logical. True = 1, False = 0

string

ASCII string. If the string contains one or more spaces, it is surrounded by double quotes (i.e. "The string"). If a quote character appears in the string, it is preceded by a backslash (`\'). A backslash character is doubled (`\\'). An empty string is also double quoted ("").

QString

ASCII string surrounded by double quotes (i.e. "The string"). If a quote character appears in the string it is preceded by a backslash. (`\').

ByteString

Byte string. Is always preceded by an attribute telling the length of the byte string.

Files

The files are found in the directory $sdtdir/INCLUDE (on UNIX), or %SDTDIR%\include (in Windows).

Interpretation of a Service Description

Below is an explanation of the different sections found in the service descriptions in Tool Services.

Description

A brief textual description of the service.

Tools Supporting the Service

The tool type(s) providing the service. Corresponds to definitions in the file sdt.h/itex.h; see Files.

Service Request

Message name. Corresponds to a definition in the file sdt.h/itex.h; see Files.

The service request is presented in a table of service parameters, with the appearance below. The parameters must appear in the order they are listed in the table. Usually, a parameter cannot be omitted. If it is optional, this is explicitly mentioned. See also Message Parameters.

Parameter Type Description
symbolic 
parameter
name

parameter
type

Brief description of the parameters.

Service Reply

Message name. Corresponds to a definition in the file sdt.h/itex.h; see Files.

The table below is similar to the service request parameter table above. A service reply always contains a status code in the first parameter. Additional parameters are only valid if the status code was OK (0). See also Message Parameters.

Parameter Type Description
status

integer

Service reply status.

Errors

Errors additional to the common errors are listed in this section; see Common Errors.

Emitted Notifications

Notifications emitted as a result of the service being successfully processed; see Notifications.


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