The Telelogic Tau Public Interface

This chapter introduces the Telelogic Tau Public Interface and describes a message based interface by which external tools and applications could be integrated with the Telelogic Tau tools.

Three conceptually different facilities are provided:

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

The Telelogic Tau Public Interface uses the PostMaster as transport. This chapter assumes the reader to be familiar with the PostMaster; see The PostMaster.

In Using the Telelogic Tau Public Interface, you may find examples of how to use the Public Interface.

Table of Contents 

• General Concepts
• Introduction
• The Public Interface
• Overview of Available Services
• Client Interface
• Message Based Services
• The Service Encapsulator
• Tool Services
• Configuration Services
• System File Services
• Link File Services
• ITEX 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
• Notifications
• Overview of Available Notifications
• Auxiliary Messages

General Concepts

Introduction

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

Application Areas

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

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

The Public Interface

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

The public interface is made available to the Telelogic Tau tools 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:
• On UNIX, important services could be executed running the Telelogic Tau tools 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 Telelogic Tau tools environment (a reference to the PostMaster is provided in The PostMaster).

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

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

Services

Provides access to functionality within the Telelogic Tau tools. Such functions could be used by external tool to control the Telelogic Tau tools, to integrate the Telelogic Tau tools with external tools or have the Telelogic Tau tools 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 the Telelogic Tau tools. Often these notifications are caused by a service being successfully processed.

Communication with SDT Simulators

When external applications are to communicate with SDT 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 by the Telelogic Tau tools for external usage. A service is normally supported by a specific tool or a few number of tools within the Telelogic Tau tools environment. 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 Telelogic Tau, and the ITEX Services are only applicable to ITEX. All other services are only applicable to ORCA¹ and SDT.

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

ITEX 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 Help Viewer Preference Manager SimUI/ValUI	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 SDT 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:

• 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:

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 Telelogic Tau tools. New tools and messages should use values above 100000. Exact numbering should follow the scheme used by the Telelogic Tau tools:

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.

• 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. If the string contains one or more spaces, it is surrounded by 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 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.

Parameter	Type	Description
symbolic parametername	parametertype	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.

The Service Encapsulator

The Service Encapsulator application enables access to Telelogic Tau tools services from the Operating System command line prompt.

Basically the tool connects to the Postmaster, sends a service request message and waits for an answer. When the answer arrives, it is printed on standard output. Finally the application exists.

The Service Encapsulator is also available in source code form to show how the Postmaster's Functional Interface could be used. A description of the internal design of the Service Encapsulator is found in Using the Telelogic Tau Public Interface. The source code of the Service Encapsulator is found in

$telelogic/examples/public_interface (on UNIX)

<SDT installation directory>\examples\public_interface (in Windows)

The Service Encapsulator binary is invoked by:

On UNIX: $telelogic/bin/serverpc <tool> <service> <params>

In Windows: <SDT installation directory>\sdtbin\serverpc <tool> <service> <params>

where <tool> is the tool that should perform the service, and <service> is the service itself.

The <tool> and <service> arguments could either be entered as a symbolic value or as the assigned integer value. These definitions are found in sdt.h

If the service takes parameters, these should be provided in <params>

Care should be taken in order to enter parameters correctly. In particular if the service uses quoted string parameters:

• On UNIX, surrounding quotes should be doubled since the shell from which the tool is invoked, consumes one pair of quotes.
• In Windows, surrounding quotes should be prefixed with a backslash (\) since the "DOS" shell from which the tool is invoked, consumes the quotes otherwise.

The tool allows carriage return "\n" and line-feed "\r" to be used.

The tool does not allow <params> to contain binary data. Therefore, SDT services accepting binary data must only contain ASCII characters.

The tool returns 0 on success and -1 if an error occur. Such errors correspond to errors when calling Postmaster functions, see SPInit, SPSendToTool, SPRead in Functional Interface for possible errors.

Tool Services

Configuration Services

Start Tool

Description

This service will start the specified tool. On UNIX, start means that a new UNIX process is "fork'ed" and "exec'ed". In Windows, start means that the applications is started using the Windows API function CreateProcess.

The Service adds "-post" to the argv[1] variable.

The parameters are recognized by the started tool in the argv[] variable starting from index 2.

The started tool inherits the environment used by the PostMaster.

The service behaves somewhat differently from other services since it is performed both in the PostMaster and in the PostMaster library in the started tool. The service is initiated in the PostMaster creating the new tool, but the service is recognized to be completed when the started tool calls the PostMaster function SPInit. This call causes a SESTARTNOTIFY message to be sent. This message is recognized by the PostMaster which upon reception of the SESTARTNOTIFY also sends a SESTARTREPLY to the issues of the start service.

The service is also different in its nature since it will cause a time-out to expire if the started tool does not call the SPInit function within a certain time limit.

The started tool must have an entry in the PostMaster configuration and the associated file containing the tool to start must exist.

The service will return to the caller:

• When the SESTARTREPLY message is received by the caller.
• If the tool is only available in one instance and is already instantiated. In this case the process id of the already instantiated tool is returned.
• If the tool cannot be started or if the tool is not recognized by the PostMaster within a time-out. (The started tool calls SPInit.)

The following MSC diagram shows the protocol when a tool is started normally (the Organizer starts the editor).

Figure 173  : Protocol to start a tool
The SESYNCCONNECT and the SESYNCCONNECTREPLY messages are not present in the Windows implementation.

Tools Supporting the Service

SET_POST

Service Request

SESTART

Parameter	Type	Description
toolType	integer	Tool type to be started
params	string	Optional. Parameters for the started tool. More than one parameter allowed. If separated with blanks, each item will be inserted into the argv[] string list for the started application. The PostMaster will add a parameter -post as the first parameter in the argv[] list.

Service Reply

SESTARTREPLY

Parameter	Type	Description
status	integer	Service reply status.
pId	integer	A PId identifying the tool type of which the corresponding type is started.

Errors

No such tool
Max instances of tool
Already started
File not found
+ Operating System file access and process creation error messages

Emitted Notifications

Notification	Description
SESTARTNOTIFY	Broadcast by the started application when calling SPInit.

Stop Tool

Description

The tool disconnects from the Postmaster and then terminates.

Tools Supporting the Service

All tools

Service Request

SESTOP

Parameter	Type	Description
force	bool	If false, the tool is allowed to reject the request. If true, the tool is expected to terminate

Service Reply

SESTOPREPLY

Parameter	Type	Description
status	integer	Service reply status
cancelled	bool	True if the tool did not accept the Stop request.

Errors

-

Get Tool Type

Description

Returns the process type for a given process id.

Tools Supporting the Service

SET_POST

Service Request

SEGETTOOLTYPE

Parameter	Type	Description
pId	integer	A PId identifying the tool type of which the corresponding type is wanted.

Service Reply

SEGETTOOLTYPEREPLY

Parameter	Type	Description
status	integer	Service reply status.
noOfToolType	integer	Number of tools corresponding to the PId value. If the requested tool type was not found in the configuration, noOfToolType is set to 0.
toolType	integer	The type of tool. If the requested PId is not found, toolType 0 is returned

Errors

-

Get Tool Pid

Description

Returns the process id for the requested tool type. If multiple instances of the tool type exist, all PId values are returned.

Tools Supporting the Service

SET_POST

Service Request

SEGETTOOLPID

Parameter	Type	Description
toolType	integer	An identifier for the tool type of which the corresponding PIds) are wanted.

Service Reply

SEGETTOOLPIDREPLY

Parameter	Type	Description
status	integer	Service reply status.
noOfPid	integer	Number of PId values corresponding to the toolType. If the requested tool type was not found in the configuration, noOfPid is set to 0.
pId	integer	A PId value corresponding to toolType

Errors

-

Add Tool

Description

Dynamically adds a tool type to the PostMaster configuration.

Tools Supporting the Service

SET_POST

Service Request

SEADDTOOL

Parameter	Type	Description
toolType	integer	An identifier for the tool. Should be a value within the allowed range.
filename	string	The filename of the executable tool. Should be a pure filename and must not include a directory path. The file should be stored on a directory that is included in the directories designated by the environment variable POSTPATH.

Service Reply

SEADDTOOLREPLY

Parameter	Type	Description
status	integer	Service reply status.
exist	bool	Returns false if the tool was inserted, true if it already existed.

Errors

Operation failed

Add Tool Subscription

Description

Dynamically adds a message to a tool's subscription list.

Tools Supporting the Service

SET_POST

Service Request

SEADDTOOLSUBSCRIPTION

Parameter	Type	Description
tooltype	integer	The tool type to which a message subscription should be added.
message	integer	The message to add to the subscription list.

Service Reply

SEADDTOOLSUBSCRIPTIONREPLY

Parameter	Type	Description
status	integer	Service reply status.
exist	bool	Returns false if the message was inserted, true if it already existed.

Errors

No such tool
Operation failed

System File Services

List System Files

Description

Lists the files currently held in the Diagram Structure chapter in the Organizer. The files will be returned in the order they are found in the Organizer (i.e. top-down, left-right).

Tools Supporting the Service

SET_ORGANIZER

Service Request

SELISTSYSTEMFILES

Parameter	Type	Description
-	-	N/A.

Service Reply

SELISTSYSTEMFILESREPLY

Parameter	Type	Description
status	integer	Service reply status.
noOfFiles	integer	Number of returned files.
file(s)	string	A list of files, with a complete directory path. Each file specification is ended by a newline.

Errors

-

New System

Description

Clear the Organizer content and create a new system. Corresponds to the Organizer menu choice New.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SENEWSYSTEM

Parameter	Type	Description
forceQuit	bool	If true, quit modified diagrams. If false and there were one or more modified diagrams, the service is denied.

Service Reply

SENEWSYSTEMREPLY

Parameter	Type	Description
status	integer	Service reply status.
cancelled	bool	True, if the service was cancelled.

Errors

Service request denied. No license available.

Open System

Description

Opens a system file and displays the file contents in the Organizer. Corresponds to the Organizer menu command Open.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SEOPENSYSTEM

Parameter	Type	Description
filename	string	The system file to open.
forceQuit	bool	If true, quit modified diagrams. If false and modified diagram(s) exist(s), the service is denied.

Service Reply

SEOPENREPLY

Parameter	Type	Description
status	integer	Service reply status.
toolType	integer	The type of tool. If the requested PId is not found, toolType 0 is returned.

Errors

Service request denied. No license available
Cannot open, system modified
Error opening system A message box displays the error

Save System

Description

Corresponds to the Organizer menu command Save. Unconnected diagrams are saved in default file names; for more information, see Save in file.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SESAVEALL

Parameter	Type	Description
systemStructureOnly	bool	True, both the system files and diagram files are saved; False, only diagram files are saved.

Service Reply

SESAVEALLREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

Service request denied. No license available
Error save all A message box displays the error

Add Existing

Description

Adds an existing document to the Organizer and optionally displays it in an editor. The type of document to be added and its corresponding editor depends on the extension of the given filename. This is the same mechanism as in the GUI-based equivalent. Corresponds to the Organizer menu choice Add Existing.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SEADDEXISTING

Parameter	Type	Description
filename	string	The document to add in the Organizer.
selected Filename	string	If there is a document connected to this file in the Organizer, the document will be selected before the Add Existing operation. In this case, the added document will be inserted before the selected document. An empty string means no selection.
start Editor	bool	If true, the added document will be popped up in an editor.
expand Substructure	bool	If true, the substructure diagrams to the added SDL diagram are added as well.

Service Reply

SEADDEXISTINGREPLY

Parameter	Type	Description
status	integer	Service reply status.
ok	bool	Returns true if the operation could be performed.

Errors

-

Link File Services

Add Local Link File

Description

Prepares a personal link file for a user. Any changes in endpoint and link information after this service is called are saved into this file. The master link file can be read only for the user at this time.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SEADDLOCALLINKFILE

Parameter	Type	Description
filename	string	File name.

Service Reply

SEADDLOCALLINKFILEREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

Merge Local Link File

Description

Merges the changes saved into the personal link file into the master link file. After a successful merge, the local link file information is cleared.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SEMERGELOCALLINKFILE

Parameter	Type	Description
-	-	N/A.

Service Reply

SEMERGELOCALLINKFILEREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

ITEX Services

Convert to GR

Description

Converts a MP file to TTCN-GR. One document file is generated in the specified destination directory. The document filename is generated by ITEX. The name of the destination directory is given. The parameter ignore page number indicates that any included page numbers in the MP file will be ignored.

The generated names are displayed in the Organizer log. For more information, see Importing a TTCN-MP Document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCONVERTTOGR

Parameter	Type	Description
filename	QString	The name of the MP file
destination	QString	The name of the destination directory
ignore page number	bool	Ignoring the included page numbers

Service Reply

IEBXCONVERTTOGRREPLY

Parameter	Type	Description
status	integer	Service reply status
itexfile	QString	The filename of the generated document.

Errors

The MP file does not exist
Illegal MP file
The file has no read permission
Unable to generate document files in the destination

Opened Documents

Description

Retrieves information about open documents known to ITEX. The EBNF follows:

DocInfoList ::= empty | DocInfoList `<NewLine>'
                DocInfo
DocInfo     ::= documentidentifier `:' buffid `:'                 itexfile `:' backupfile

Tools Supporting the Service

IET_BASE

Service Request

IEBXOPENEDDOCUMENTS

Service Reply

IEBXOPENEDDOCUMENTSREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
infolist	EBNF	The list of open documents identifiers, buffer identifiers and database file.

Errors

-

Fetch Buffer Identifier Given the Database

Description

Given a database, this function fetches the document buffer identifier if the document is open.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETBUFFIDFROMPATH

Parameter	Type	Description
itexfile	QString	The database path in the local system syntax.

Service Reply

IEBXGETBUFFIDFROMPATHREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
buffid	integer	The document's buffer identifier

Errors

Unable to find database

Fetch Buffer Identifier Given MP File Path

Description

Given a MP file path this function fetches the document buffer identifier if there is any database generated from this MP and the document in the database is open.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETBUFFIDFROMMPPATH

Parameter	Type	Description
mpfile	QString	The MP file path in the local system syntax.

Service Reply

IEBXGETBUFFIDFROMMPPATHREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
buffid	integer	The document's buffer identifier

Errors

Unable to find database

Convert to MP

Description

Generates a MP file for the given system node. This converts the entire document source (all TTCN objects) and does not consider the selection. The document must be connected but not necessarily open.

For more information, see Exporting a TTCN Document to TTCN-MP.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCONVERTTOMP

Parameter	Type	Description
buffid	integer	The document's buffer identifier
standard flag	bool	Indicates if the MP shall be TTCN standard. (True if standard MP is required.)
filename	QString	The MP filename

Service Reply

IEBXCONVERTTOMPREPLY

Parameter	Type	Description
status	integer	Service reply status

Errors

Invalid buffer identifier
The document is not connected
Unable to write file

Convert Selection to MP

Description

Generates a MP file for the given system node. It converts only the selected parts of the document which means that the document needs both to be connected and open.

For more information, see Exporting a TTCN Document to TTCN-MP.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCONVERTSELTOMP

Parameter	Type	Description
buffid	integer	The document's buffer identifier
standard flag	bool	Indicates if the MP shall be TTCN standard. (True if standard MP is required.)
filename	QString	The MP filename

Service Reply

IEBXCONVERTSELTOMPREPLY

Parameter	Type	Description
status	integer	Service reply status

Errors

Invalid buffer identifier
The document is not connected
The document is not open
Unable to write file

Merge Document

Description

This function is used to merge one document into another document. Both the source and the destination documents must be available to the ITEX environment, i.e. both documents must be loaded. Furthermore a selection must exists in the source document.

For more information, see Merging TTCN Documents.

Tools Supporting the Service

IET_BASE

Service Request

IEBXMERGEDOCUMENT

Parameter	Type	Description
srcbuffid	integer	The source document's buffer identifier
destbuffid	integer	The destination document's buffer identifier

Service Reply

IEBXMERGEDOCUMENTREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).

Errors

Unable to merge documents

Analyze Document

Description

Analyze the given system node.

For more information, see Analyzing TTCN Documents (on UNIX), or Analyzing TTCN Documents (in Windows).

Tools Supporting the Service

IET_BASE

Service Request

IEBXANALYZE

Parameter	Type	Description
buffid	integer	The document's buffer identifier
forced analysis	bool	Set if forced analysis should be in effect
verbose	bool	Indicates if verbose mode is to be on
errorlimit	integer	Max number of errors before aborting

Service Reply

IEBXANALYZEREPLY

Parameter	Type	Description
status	integer	Service reply status

Errors

Invalid buffer identifier
The document is not connected

Close Document

Description

This function closes the document and all open tables in it.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCLOSEDOCUMENT

Parameter	Type	Description
buffid	integer	The document's buffer identifier

Service Reply

IEBXCLOSEDOCUMENTREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).

Errors

Invalid buffer identifier
Unable to close document

Save Document

Description

Given the buffer identifier of the document the corresponding system node is saved in the given filename.

Tools Supporting the Service

IET_BASE

Service Request

IEBXSAVE

Parameter	Type	Description
buffid	integer	The document reference
filename	QString	The filename where the document source must be saved.

Service Reply

IEBXSAVEREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

No such tool
Invalid buffer identifier
Couldn't write file

Selector

Description

Given restrictions and a database this function selects all objects which fulfill the restrictions. For more information, see Using More Complex Selections.

Tools Supporting the Service

IET_BASE

Service Request

IEBXSELECTOR

Parameter	Type	Description
buffid	integer	The document's buffer identifier
namerestr	string	The name restriction.
typerestr	string	The content restriction.
contentrestr	string	The type restriction.
selectormode	string	The selector mode (restrict, extend or replace REL where REL is references, references_recursive or referenced_by)
analysestatus	string	The analysis status (not_analyzed, error_analyzed or ok_analyzed)

Service Reply

IEBXSELECTORREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).

Errors

No such tool
Invalid buffer identifier

SelectAll

Description

Select all objects in the document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXSELECTALL

Parameter	Type	Description
buffid	integer	The document's buffer identifier

Service Reply

IEBXSELECTALLREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).

Errors

Invalid buffer identifier

DeselectAll

Description

Remove all selections in the document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXDESELECTALL

Parameter	Type	Description
buffid	integer	The document's buffer identifier

Service Reply

IEBXDESELECTALLREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).

Errors

Invalid buffer identifier

IsSelected

Description

This function checks if there is any object selected in the document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXISSELECTED

Parameter	Type	Description
buffid	integer	The document's buffer identifier

Service Reply

IEBXISSELECTEDREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
selectstate	bool	Indicates if there is any selected objects in the document.

Errors

Invalid buffer identifier

Get Modify Time

Description

This function fetches the modify time of a document.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETDOCUMENTMODIFYTIME

Parameter	Type	Description
buffid	integer	The document's buffer identifier

Service Reply

IEBXGETDOCUMENTMODIFYTIMEREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
modifytime	QString	The modify time of the document.

Errors

Invalid buffer identifier

Get Path

Description

Given a document buffer identifier this function fetches the corresponding database path.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETPATH

Parameter	Type	Description
buffid	integer	The document's buffer identifier

Service Reply

IEBXGETPATHREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
itexfile	QString	The database path in the local system syntax.

Errors

Invalid buffer identifier

Get MP Path

Description

Given a document bufferid this function fetches the corresponding MP file path.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETMPPATH

Parameter	Type	Description
buffid	integer	The document's buffer identifier

Service Reply

IEBXGETMPPATHREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
mpfile	QString	The MP file path in the local system syntax.

Errors

Invalid buffer identifier

Find Table

Description

Given the buffer identifier of the selected document and a table identifier, ITEX searches for the table. The found table is displayed in the Table Editor.

Tools Supporting the Service

IET_BASE

Service Request

IEBXFINDTABLE

Parameter	Type	Description
buffid	integer	The document's buffer identifier
tableid	QString	The name of the table to find

Service Reply

IEBXFINDTABLEREPLY

Parameter	Type	Description
status	integer	Service reply status

Errors

Invalid buffer identifier
Unconnected document

Close Table

Description

Close the given table.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCLOSETABLE

Parameter	Type	Description
buffid	integer	The document's buffer identifier
tableident	QString	The table identifier.

Service Reply

IEBXCLOSETABLEREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).

Errors

Invalid buffer identifier
No such object

Get Table State

Description

This function returns the status of a given table. The status a table indicates if the table is open or close.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETTABLESTATE

Parameter	Type	Description
buffid	integer	The document's buffer identifier
tableident	QString	The table identifier.

Service Reply

IEBXGETTABLESTATEREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
tablestate	QString	Returns open, close, row_in_open or row_in_close.

Errors

Invalid buffer identifier
No such object

Get Row Number

Description

Given the name of a row this function returns the number (position) of it in the table. The row can be a row in a single or multiple table.

Tools Supporting the Service

IET_BASE

Service Request

IEBXGETROWNUMBER

Parameter	Type	Description
buffid	integer	The document's buffer identifier
tableident	QString	The table identifier.
rowname	identifier	The name of the row.

Service Reply

IEBXGETROWNUMBERREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
rownumber	integer	The number of the given row. The first row has number one.

Errors

Invalid buffer identifier
No such object
No such row

Select Row

Description

This function modifies the selection status of a given row in a table.

Tools Supporting the Service

IET_BASE

Service Request

IEBXSELECTROW

Parameter	Type	Description
buffid	integer	The document's buffer identifier
tableident	QString	The table identifier.
rownumber	integer	The number of the row.
selectstate	bool	The select status of the row to be modified.

Service Reply

IEBXSELECTROWREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
exist	bool	Returns false if the message was inserted, true if it already existed.

Errors

Invalid buffer identifier
No such object
No such rownumber

Clear Selection

Description

This function removes all row selections in a table.

Tools Supporting the Service

IET_BASE

Service Request

IEBXCLEARSELECTION

Parameter	Type	Description
buffid	integer	The document's buffer identifier
tableident	QString	The table identifier.

Service Reply

IEBXCLEARSELECTIONREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).

Errors

Invalid buffer identifier
No such object

Rows Selected

Description

Given the buffer identifier and the table identifier, this function returns the numbers of the selected rows in a table (the first row has number 1).

Tools Supporting the Service

IET_BASE

Service Request

IEBXROWSSELECTED

Parameter	Type	Description
buffid	integer	The document's buffer identifier
tableident	QString	The table identifier.

Service Reply

IEBXROWSSELECTEDREPLY

Parameter	Type	Description
status	integer	Service reply status (zero if the operation does not fail).
nonezero*	integer	A list of selected row numbers. The list is empty if no row is selected.

Errors

Invalid buffer identifier
No such object

Menu Manipulation Services

Introduction

All graphical tools in ORCA and SDT support customizable menus. These user-defined menus will be appended to the menu bar of the tool. The exact location will be defined by the tool, depending on the abilities of the graphical framework the tool is built upon.

The intention is to have an external tool to configure a tool in order to provide the necessary UI. Telelogic tools could also take advantage of these extendable menus.

The following operations are available through a set of well defined PostMaster messages:

• Creating a menu
• Creating a menu choice
• Deleting a menu

Each menu choice can be associated to any of the following:

• A PostMaster message
• An operating system command

Add Menu

Description

Adds a new menu to the menu bar.

Tools Supporting the Service

SET_ORGANIZER
SET_SDLE
SET_MSCE
SET_OME
SET_TE
SET_SIMULATOR_UI 2
SET_FILEVIEWER
SET_COVERAGEVIEWER
SET_XREFVIEWER
SET_TYPEVIEWER
SET_TREEVIEWER
SET_PREFERENCES
SET_HELPVIEWER

Service Request

SEMENUADD

Parameter	Type	Description
menuName	string	Name of the menu to add.

Service Reply

SEMENUADDREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

Delete Menu

Description

Removes the menu and its menu choices from the menu bar.

Tools Supporting the Service

SET_ORGANIZER
SET_SDLE
SET_MSCE
SET_OME
SET_TE
SET_SIMULATOR_UI 3
SET_FILEVIEWER
SET_COVERAGEVIEWER
SET_XREFVIEWER
SET_TYPEVIEWER
SET_TREEVIEWER
SET_PREFERENCES
SET_HELPVIEWER

Service Request

SEMENUDELETE

Parameter	Type	Description
menuName	string	Name of the menu to delete.

Service Reply

SEMENUDELETEREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

Clear Menu

Description

Clears the menu bar from a menu item.

Tools Supporting the Service

SET_ORGANIZER
SET_SDLE
SET_MSCE
SET_OME
SET_TE
SET_SIMULATOR_UI 4
SET_FILEVIEWER
SET_COVERAGEVIEWER
SET_XREFVIEWER
SET_TYPEVIEWER
SET_TREEVIEWER
SET_PREFERENCES
SET_HELPVIEWER

Service Request

SEMENUCLEAR

Parameter	Type	Description
menuName	string	Name of the menu to clear.

Service Reply

SEMENUCLEARREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

Add Item to Menu

Description

Adds a menu choice to the specified menu. The menu choice could either perform an OS command or issue a PostMaster notification when selected. The OS command to perform or the message to broadcast could be sensitive on a selected symbol.

The description of the service parameters below is generic to all tools supporting the service. Some tools have special interpretations of some parameters. Some tools also allow format codes to be used in the command string or as message parameter, providing additional context sensitive information. Both these tool-specific issues are described separately in the following sections:

• Add Item to Menu -- Organizer
• Add Item to Menu -- Text Editor
• Add Item to Menu -- Graphical Editors

Tools Supporting the Service

SET_ORGANIZER
SET_SDLE
SET_MSCE
SET_OME
SET_TE
SET_SIMULATOR_UI 5
SET_FILEVIEWER
SET_COVERAGEVIEWER
SET_XREFVIEWER
SET_TYPEVIEWER
SET_TREEVIEWER
SET_PREFERENCES
SET_HELPVIEWER

Service Request

SEMENUADDITEM

Parameter	Type	Description
menuName	string	The menu in which an item should be added.
menuItem	string	Name of menu item to add.
separator	bool	If a separator should precede the item.
statusText	string	The status text to show when the menu item is selected.
notUsed1 lastAction ProprietaryKey (tool-specific)	integer	The interpretation of this parameter is tool-specific; see the separate tool descriptions later. If not used, this parameter should be set to 0.
notUsed2 AttributeKey (tool-specific)	integer	The interpretation of this parameter is tool-specific; see the separate tool descriptions later. If not used, this parameter should be set to 0.
scope	integer	Indicates when the menu item should be dimmed. The possible values are tool-specific; see the separate tool descriptions later. If not used, this parameter should be set to:
		ALWAYS (0) The menu choice will always be available, independently of the selection in the tool's active window.
confirmText	string	If no text is provided, no confirmation is assumed. A non-empty text denotes confirmation; a two button dialog will be issued with the choices OK and Cancel. The dialog text is defined in confirmText. In an associated user editable field, the expanded action to perform is displayed.
actionType	integer	The value controls the last part of the message which is variant. 0 = PostMaster message 1 = OS command.

• If actionType above sets the variant part to be a PostMaster message, the last two parameters are:

Parameter	Type	Description
message	integer	Interpreted as the PostMaster message to send.
params	string	Interpreted as the parameters to the PostMaster message. Tool-specific context sensitive format codes are evaluated; see the separate tool descriptions later.

• If actionType above sets the variant part to be an OS command, the last two parameters are:

Parameter	Type	Description
OSblock	bool	Whether to wait for the command to finish before giving control to the user.
OScommand	string	The OS command to perform. Tool-specific context sensitive format codes are evaluated; see the separate tool descriptions later.

Service Reply

SEMENUADDITEMREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

Add Item to Menu -- Organizer

Description

Identical to the description of Add Item to Menu, except that the semantics of the parameters and supported format codes for the service differ.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SEMENUADDITEM

Format Codes

The following format codes are recognized. There are format modifiers for some of the basic formats:

• B -- the base filename
• D -- the directory part of the full filename
• R -- the filename, relative to the source directory

Format code	Description
%b %Bb, %Db %Rb	The file name of the system file associated to the Organizer window.
%f %Bf %Df %Rf	The name of the file that contains the selected object.
%F %BF %DF %RF	All files in the substructure of the selected object (including the selected object).
%l %Bl %Dl %Rl	The name of the link file loaded in the Organizer.
%o %Bo %Do %Ro	The name of the Control Unit file for the selected object.
%r	Perform the command recursively on all files in the substructure of the selected object (including the selected object).
%u	The source directory.
%v	The target directory.

Parameters

Apart from providing a set of format codes, the Organizer gives special interpretation to the lastAction and scope parameters.

Parameter	Type	Description
lastAction	integer	Controls what happens when a dynamic menu command has been performed. Only available when actionType is OS Command. This attribute should be one of the following:
		NOTHING (0) Perform no action.
		CHECK_FILE (1) A check file operation is performed on the selected object when the OS command is completed. If the OS command is non-blocking, the command is performed as soon as the OS command has been issued.
		CHECK_FILE_ON_RECURSIVE (2) This flag works as the CHECK_FILE flag but is used only with a %r command.
scope	integer	This attribute could be one of the following:
		ALWAYS (0) The menu choice will always be available, independently of the selection in the tool's active window.
		ONE_SELECTED_OBJECT (1) The menu choice is available if one object is selected.
		SELECTED_OBJECT_NOT_IN_EDITOR (4) The menu choice is available if one object is selected and the selected object is not loaded in an editor.
		VALID_SELECTED_OBJECT (5) The menu choice is available if one object is selected and the object is not marked invalid.
		SELECTED_GROUP_NOT_IN_EDITOR (6) The menu choice is available if one object is selected and no diagram of the document group for the selected object is loaded in an editor.

Add Item to Menu -- Text Editor

Description

Identical to the description of Add Item to Menu, except that the semantics of the parameters and supported format codes for the service differ.

Tools Supporting the Service

SET_TE

Service Request

SEMENUADDITEM

Format Codes

The following format codes are recognized.

Format code	Description
%f	The filename of the document.
%u	The source directory
%s	The selected text
%S	The entire text of the document.

Add Item to Menu -- Graphical Editors

Description

Identical to the description of Add Item to Menu, except that the semantic of the parameters and supported format codes for the service differ.

Tools Supporting the Service

SET_SDLE
SET_MSCE
SET_OME

Service Request

SEMENUADDITEM

Format Codes

The following format codes are recognized.

Format code	Description
%a	The absolute name of the file associated with the selected object. Extracted from the SDT reference.
%b	The absolute name of the file associated to the window.
%c	If the selected object uses extended data, the comment is extracted.
%d	If the selected object uses extended data, the data part is extracted.
%e	The text in the object. (Only in the SDL Editor.)
%f	The name of the file that contains the object.
%g	The SDT reference to the object.
%p	The page name currently shown in the window (not applicable to the MSC Editor).
%s	The name of the file shown in the window.
%t	The page name for the object (not applicable to the MSC Editor). Extracted from the SDT reference.

Parameters

Apart from providing a set of format codes, the graphical editors give special interpretation to the lastAction, ProprietaryKey and AttributeKey parameters.

Parameter	Type	Description
ProprietaryKey	integer	The keys ProprietaryKey and AttributeKey are used to determine whether or not a menu choice should be available (i.e. dimmed or not). See Editor -- Object Services for more information.
AttributeKey	integer	See description of ProprietaryKey.
scope	integer	This attribute should be one of the following:
		ALWAYS (0) The menu choice will always be available, independently of the selection in the tool's active window. The keys ProprietaryKey and AttributeKey are handled as don't care.
		ONE_SELECTED_OBJECT1 (1) The menu choice is available only if exactly one object is selected. The keys ProprietaryKey and AttributeKey are handled as don't care.
		MATCHING_KEYS (2) The menu choice is available only if at least one of the selected objects has an attribute that matches the keys above.
		MATCHING_KEYS_ONE_SELECTED_OBJECT (3)1 The menu choice is available only if exactly one object is selected and it has an attribute that matches the keys above.

Logging Services

Start MSC Log

Description

Starts the logging of messages sent by tools connected to the PostMaster. The format used by the log is event-oriented MSC-PR.

Tools Supporting the Service

SET_POST

Service Request

SESTARTTRACE

Parameter	Type	Description
filename	string	The name of the file on which the log should be stored. If the parameter is omitted, the default log file post.mpr will be used. If the parameter is set to "-e", logging is done on standard error.
logMode	integer	If not set, only public messages are logged. If set to a value > 2 all messages are logged.

Service Reply

SESTARTTRACEREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

Stop MSC Log

Description

Stops the logging of messages sent by PostMaster tools.

Tools Supporting the Service

SET_POST

Service Request

SESTOPTRACE

Parameter	Type	Description
-	-	N/A.

Service Reply

SESTOPTRACEREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

-

SDT Reference Services

Show SDT Source

Description

Selects the SDT reference in an editor. A reference could be:

• An SDL reference.

The reference is shown in an SDL Editor.

• An MSC reference.

The reference is shown in an MSC Editor.

• An OM reference.

The reference is shown in an OM Editor.

• A text reference

The reference is shown in a text editor. The text editor is chosen by the preference SDT* TextEditor.

For a complete description of the format of an SDT reference, please see SDT References.

Tools Supporting the Service

SET_ORGANIZER

Service Request

SESHOWREF

Parameter	Type	Description
SDTRef	string	A valid SDT reference.

Service Reply

SESHOWREFREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

 SDT Reference Errors

Emitted Notifications

Notification	Description
SELOADNOTIFY	If any editor loaded the required diagram.
SESDLELOADNOTIFY	If the SDL Editor loaded the required diagram.
SEOMELOADNOTIFY	If the OM editor loaded the required diagram.
SESTARTNOTIFY	If the editor was started.

Obtain GR Reference

Description

Returns the SDT references for the current selection(s) in the editors.

Tools Supporting the Service

SET_SDLE
SET_MSCE
SET_OME

Service Request

SEOBTAINGRREF

Parameter	Type	Description
-	-	N/A

Service Reply

SEOBTAINGRREFREPLY

Parameter	Type	Description
status	integer	Service reply status.
NoOfRef	integer	The number of references found.
ref*	string	A complete SDT reference.

Errors

 SDT Reference Errors
Illegal use of qualifier
Illegal reference type

Editor -- Diagram Services

The Buffer Concept

The editor defines the concept buffer, which basically identifies a diagram currently loaded in the editor. Each buffer is identified with a buffer id which is unique within one session of the editor as long as the editor is not stopped)

A buffer id is returned when an existing diagram is successfully loaded in an editor or a new diagram is created and implicitly loaded in the editor. Then, most services manipulating diagrams in editors, refer to the buffer containing the diagram via the buffer id.

Load Diagram

Description

Loads a diagram or text document specified by filename in an editor buffer. If the diagram was already loaded, the existing buffer id will be returned.

Tools Supporting the Service

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Service Request

SELOAD

Parameter	Type	Description
filename	string	The diagram file to load specified with the full directory path.

Service Reply

SELOADREPLY

Parameter	Type	Description
status	integer	Service reply status.
bufId	integer	Refers to an allocated buffer in the editor.
type	integer	The type of diagram.
name	string	The name of the loaded diagram.

Errors

Can not read file <filename> <error message> 
SDLE is busy, syntax error in text   (SDLE only)

Emitted Notifications

Notification	Description
SELOADNOTIFY	If the diagram was loaded.
SESDLELOADNOTIFY	If an SDL diagram was loaded.
SEOMELOADNOTIFY	If an OM, SC or HMSC diagram was loaded.

Unload Diagram

Description

Unloads a diagram from an editor.

Tools Supporting the Service

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Service Request

SEUNLOAD

Parameter	Type	Description
bufId	integer	Refers to a buffer in the editor.
forceUnload	bool	If true, the editor will force a modified diagram to be unloaded. If false, the editor will not unload the diagram if it is modified.

Service Reply

SEUNLOADREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

Invalid diagram buffer id
Diagram is changed If force Unload is false
SDLE is busy, syntax error in text   (SDLE only)

Emitted Notifications

Notification	Description
SEUNLOADNOTIFY	If the diagram was unloaded.

Show Diagram

Description

The service will raise a window in the editor showing the specified buffer.

Tools Supporting the Service

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Service Request

SESHOW

Parameter	Type	Description
bufId	integer	Refers to a buffer in the editor.
pageName	string	Name of the page to show. If the string is empty, the last recently used, or if no such page exist, the default page will be shown. Applicable all diagrams except MSC and text documents. For MSC diagrams this parameter may be omitted or left empty. For text document (loaded in the TE), this option is ignored.

Service Reply

SESHOWREPLY

Parameter	Type	Description
status	integer	Service reply status.

Errors

Invalid diagram buffer id
Unable to open page   (SDLE/OME only)
SDLE is busy, syntax error in text   (SDLE only)

Emitted Notifications

Notification	Description
SESHOWNOTIFY	If the diagram was raised.

Save Diagram

Description

The service will save the diagram in the specified file. If not a valid filename or if there is no permission to save the file, an error will be returned. When saved, the editor buffer is marked as not edited.

Tools Supporting the Service

SET_SDLE
SET_MSCE
SET_OME
SET_TE

Service Request

SESAVE

Parameter	Type	Description
bufId	integer	Refers to a buffer in the editor.
filename	string	The file where to save the buffer.

Service Reply

SESAVEREPLY

Parameter	Type	Description
status	integer	Service reply status.
saveok	bool	Returns true if the buffer was successfully saved.

Errors

Invalid diagram buffer Id
Diagram is new. Filename is missing. 
Cannot save file <filename> <error message>
SDLE is busy, syntax error in text   (SDLE only)

Emitted Notifications

Notification	Description
SESAVENOTIFY	If the diagram was saved.

Create SDL Diagram

Description

Creates an empty SDL diagram in a new buffer. The diagram gets an unconnected status. Corresponds to SDL Editor command New.

Tools Supporting the Service

SET_SDLE

Service Request

SESDLECREATEDIAGRAM

Parameter	Type	Description
virtuality	integer	Kind of virtuality. Only applicable to typed diagrams. Other diagrams should use the value NOVIRTUAL Possible values are: NOVIRTUAL VIRTUAL REDEFINED FINALIZED These values are defined in sdtsym.h
DiagramType	integer	Diagram type. See sdtsym.h for valid diagram types.
name	string	Diagram name.
qualifier	string	SDL qualifier. Could be empty.
pageType	integer	Type of the first page in the diagram. See sdtsym.h for valid page types. Note that the pageType must correspond with the diagramType.
pageName	string	Name of the first page in the diagram.