Previous Chapter 43 The SDT Public Interface

43 The SDT Public Interface

This chapter introduces the SDT Public Interface and describes a message based interface by which external tools and applications could be integrated with SDT. Three conceptually different facilities are provided.

By controlling the behavior of SDT and by modifying data SDT handles.
By listening to important events of status change in SDT.
By integrating an external application with SDT simulators.

The SDT Public Interface uses the SDT PostMaster as transport. This chapter assumes the reader to be familiar with the SDT PostMaster. In chapter 10, How to Use the SDT Public Interface, you may find examples of how to use the interface.

General Concepts

Introduction

In SDT-3 significant steps have been made to increase the openness of SDT by the introduction of the SDT Public Interface. Openness is provided both in terms of diverse ways of controlling SDT and the way data handled by SDT are made visible.

Application Areas

Two different kinds of usage of SDT could be foreseen:

As an alternate or complementary, compared to the normal graphical interface, means to access functionality provided by SDT. Such usage could be to integrate simulators generated by SDT with dedicated user interfaces or to use the SDT batch facilities using make or print in a large "build" environment.
Integrating SDT with other tools forming a larger environment.

The Public Interface

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

The public interface is made available to SDT users 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 SDT in a batch mode.
- A service encapsulator could be run, which allows message based services to be issued. This tool is made available as a an example application.

The PostMaster

The PostMaster forms an integral mechanism to integrate tools in the SDT environment (a reference to the PostMaster is provided in chapter 42, The SDT PostMaster).

It is also used as a low level mechanism to physically integrate SDT 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 SDT services. These are built up of Services and Notifications. A special case of service is Communication with Simulators.

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

Services

Provides access to functionality within SDT. Such functions could be used by external tool to control SDT, to integrate SDT with external tools or have SDT 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 broadcasted messages which are spontaneously emitted when a significant event takes place in SDT. Often these notifications are caused by a service being successfully processed.

Communication with Simulators

When external applications are to communicate with simulators, the message SESDLSIGNAL is used. It is asynchronously sent/broadcasted 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 by SDT for external usage. A service is normally supported by a specific tool or a few number of tools within the SDT environment. Some of the services correspond to a menu choice or an operation performed by a user using the tools's graphical interface.

Configuration Services

---------------------------------------------------
Service                Servers     Graphical         
                                   correspondence    
---------------------------------------------------
Start Tool             PostMaster  Start a new tool  
Get Tool Type          PostMaster  N/A               
Get Tool Pid           PostMaster  N/A               
Add Tool               PostMaster  N/A               
Add Tool Subscription  PostMaster  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 SDT Source      Organizer  Show source menu choice  
Obtain GR Reference  SDLE       N/A                      
                     MSCE                                
-------------------------------------------------------

System File Services

------------------------------------------------------
Service            Servers    Graphical correspondence  
------------------------------------------------------
List System Files  Organizer  N/A                       
Open System        Organizer  Open quick button         
Save System        Organizer  Save quick button         
------------------------------------------------------

Diagram Management Services

------------------------------------------------------
Service             Servers  Graphical correspondence   
------------------------------------------------------
Load Diagram        SDLE     Open diagram menu choice   
                    MSCE                                
Unload Diagram      SDLE     Close diagram menu choice  
                    MSCE                                
Save Diagram        SDLE     Save diagram menu choice   
                    MSCE                                
Create SDL Diagram  SDLE     New diagram menu choice    
                    MSCE                                
Create MSC Dia      SDLE     New diagram menu choice    
gram                MSCE                                
------------------------------------------------------

Diagram Object Management Services

----------------------------------------------------
Service            Servers  Graphical correspondence  
----------------------------------------------------
Select Object      SDLE     Selecting an object       
                   MSCE                               
Insert SDL Object  SDLE     Select object in symbol   
                            menu                      
Insert MSC Object  MSCE     Select object in symbol   
                            menu                      
Remove Object      SDLE     Clear menu choice         
                   MSCE                               
Show Object        SDLE     Selecting an object       
                   MSCE                               
----------------------------------------------------

Menu Management Services

---------------------------------------------------
Service           Servers  Graphical correspondence  
---------------------------------------------------
Add Menu          SDLE     N/A                       
                  MSCE                               
Delete Menu       SDLE     N/A                       
                  MSCE                               
Clear Menu        SDLE     N/A                       
                  MSCE                               
Add Item to Menu  SDLE     N/A                       
                  MSCE                               
---------------------------------------------------

Object Data Management Services

---------------------------------------------------
Service           Servers  Graphical correspondence  
---------------------------------------------------
Display Key       SDLE     N/A                       
                  MSCE                               
List Key          SDLE     N/A                       
                  MSCE                               
Create Attribute  SDLE     N/A                       
                  MSCE                               
Read Attribute    SDLE     N/A                       
                  MSCE                               
Update Attribute  SDLE     N/A                       
                  MSCE                               
Delete Attribute  SDLE     N/A                       
                  MSCE                               
---------------------------------------------------

Information Server Services

------------------------------------------------------------
Service               Servers       Graphical correspondence  
------------------------------------------------------------
Load Definition File  Information   N/A                       
                      Server                                  
------------------------------------------------------------

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 SDT 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.
A change in this file is kind of static nature, since the configuration files are read every time the PostMaster (SDT) is started.
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 SDT. New tools and messages should use values above 100000. Exact numbering should follow the scheme used by SDT:

------------------------------------------------------------------
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 noti   
                 fication. and add the messages sequentially.       
------------------------------------------------------------------

Message Based Services

Introduction

Using a message based services 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.

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.
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 could 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 chapter 41, References in SDT-3.

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'.
- The character `+' might also appear as an alternative. The difference is that one or more is expected.
A preceding attribute tells how many items to expect.

The following parameter types are used:

-----------------------------------------------------------------
Type          Description                                          
-----------------------------------------------------------------
integer       32 bit integer in ASCII form.                        
bool          Logical. True = 1, False = 0                         
string        ASCII string.                                        
QuotedString  ASCII string surrounded by double quotes (i.e.       
              "The string"). If a quote character appears in the   
              string it is proceeded by a backslash. (`\'). An     
              empty string is also double quoted ("").             
ByteString    Byte string. Is always preceded by an attribute      
              telling the length of the byte string.               
-----------------------------------------------------------------

Files

The file sdt.h provides a list of the available services and notifications in terms of message definitions. It also defines a list (see "Adding Tools and Messages" on page 2486 in chapter 42, The SDT PostMaster) 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.

The files are found in the directory $sdtdir/INCLUDE.

Interpretation of a Service Description

Below is an explanation of the different sections found in a service description.