![]() |
![]() |
![]() |
![]() |
![]() |
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:
- As an alternate or complementary means to access functionality provided by the tools, compared to the normal graphical interface. Such usage could be to integrate simulators generated by the tools with dedicated user interfaces, or to use the tools batch facilities using make or print in a large "build" environment.
- Integrating SDL Suite and TTCN Suite tools with other tools forming a larger environment.
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.
- Via a programming interface, providing message based services and notifications. The rest of this section provides a description of these services and notifications and their usage.
- Via applications executed via the OS command line interface. By using this interface:
- Important services could be executed running in a batch mode.
- A Service Encapsulator could be run, which allows message based services to be issued. This tool is also made available as a an example application. For more information, see The Service Encapsulator.
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:
- It maintains a list on known tools. Such tools could be connected to the PostMaster and thereby taking part of message sending
- It provides means to broadcast messages to a list of subscribers
- It contains functionality to send a message to a certain recipient.
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
System File Services
Link File Services
TTCN Suite Services
Menu Manipulation Services
Logging Services
SDT Reference Services
Editor - Diagram Services
Editor - Object Services
Editor - Object Attribute Services
Information Server Services
SDL Editor Services
SC Editor Services
MSC Editor Services
HMSC Editor Services
CIF Services
Text Editor Services
Client Interface
A client which would like to make an integration using these facilities should consult the following interface:
- A programming interface to communicate with the PostMaster
- A description of the provided services
- A description of the available notifications
External Client types
Clients connecting to the PostMaster must be known by the PostMaster. This can be accomplished in a number of ways:
- 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.
- 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:
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:
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.
- 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.
- While processing the service.
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 parametersServer busyService not supportedServer lockedSDT Reference Errors
When a service request refers to an SDT reference, the following errors may occur:
Reference must contain paranthesisReference must start with #SDTREFInvalid referenceGarbage after referenceEmbedded value not terminatedIllegal value in paranthesis after token <token-nr>Junk after embedded valueIncomplete reference lacking trailing paranthesisUnsupported reference type <token>Symbol must be integer >= 0Malformed coordinateFor 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.
- Parameters are normally separated by a blank (` `) character.
- A parameter that has an additional `*' character is a shorthand for none or a number of this type, each one separated by a blank ` ` or a newline `\n'.
- A preceding attribute tells how many items to expect.
The following parameter types are used:
Files
- The files sdt.h and itex.h provides two lists of the available services and notifications in terms of message definitions. It also defines a list (see Adding Tools and Messages) providing a textual definition of messages.
- The file sdtsym.h provides the definitions necessary when working with editors and defines values for diagram types, pages types and symbol types.
- In Windows, the file post.dll is the DLL that contains the external PostMaster interface. It needs either reside in the same directory as the application that is utilizing it, or in a directory that is in the current PATH.
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.
symbolic parameter name parameter typeService 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.
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 |
![]() |
![]() |
![]() |
![]() |