IBM
Contents Index Previous Next



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:

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

Figure 160 : 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

Substruct
ure

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

-

TTCN Suite 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 the TTCN Suite. 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

Load Document

Description

Given a source file path this function load the document. Then this document may be shown in the TTCN Browser using "Show" service. The source file may have MP format or TTCN GR format.

Note

Available on Windows only.

Tools Supporting the Service
IET_BASE
Service Request
SELOAD

Parameter Type Description
filename

QString

The filename

Service Reply

SELOADREPLY

Parameter Type Description
status

integer

Service reply status (zero if the operation does not fail).

buffid

integer

The document's buffer identifier

Errors
No such file or directory
Syntax error

Show Document

Description

Show the given document in the TTCN Browser.

Tools Supporting the Service
IET_BASE
Service Request
SESHOW

Parameter Type Description
buffid

integer

The document's buffer identifier

Service Reply
SESHOWREPLY

Parameter Type Description
status

integer

Service reply status (zero if the operation does not fail).

Errors
Invalid buffer identifier

Opened Documents

Description

Retrieves information about open documents known to TTCN Suite. 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 TTCN Suite 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.

Note

Available on UNIX only.

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, TTCN Suite 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 the SDL Suite 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. SDL Suite and TTCN Suite could also take advantage of these extendable menus.

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

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

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 1
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 2
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 3
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:

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
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.

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.

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:

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.




CM_UPDATE (4)

    
Perform a CM_UPDATE operation on the closest *.scu file.




SHOW_LOG (8)

    
Show the Organizer Log window (where textual output from the OS command is presented).
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_E
DITOR (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_SELEC
TED_OBJECT (3)a.

    
The menu choice is available only if exactly one object is selected and it has an attribute that matches the keys above.
1

Each tool should define and adopt conventions for when exactly one object only is considered as selected. For instance, selecting a task symbol in an SDL Editor also selects the from and to lines. However, attaching information to these lines does not fill any meaningful purpose; the SDL Editor considers the situation as if one object only (i.e. the task symbol) was selected.

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 Source

Description

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

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.

Service Reply
SESDLECREATEDIAGRAMREPLY

Parameter Type Description
status

integer

Service reply status.

bufId

integer

Refers to a buffer in the editor.

Errors
SDLE is busy, syntax error in text
Emitted Notifications

Notification Description
SESDLECREATENOTIFY

As a result of creating the diagram.

SEPAGENOTIFY

As a result of creating a page.

Create MSC Diagram

Description

Creates an empty MSC diagram in new buffer. Corresponds to MSC Editor command New.

Tools Supporting the Service
SET_MSCE
Service Request
SEMSCECREATEDIAGRAM

Parameter Type Description
diagramType

integer

Diagram type. Defined in sdtsym.h. The value MSCDIAGRAM (16) should be used.

name

string

Name of the diagram to create.

qualifier

string

For future use. Should be empty.

Service Reply
SEMSCECREATEDIAGRAMREPLY

Parameter Type Description
status

integer

Service reply status.

bufId

integer

Refers to a buffer in the editor.

Errors

-

Emitted Notifications

Notification Description
SEMSCENEWNOTIFY

As a result of creating the diagram.

Create OM Diagram

Description

Creates an empty OM diagram in new buffer. Corresponds to OM Editor command New.

Tools Supporting the Service
SET_OME
Service Request
SEOMECREATEDIAGRAM

Parameter Type Description
diagramType

integer

Diagram type. Defined in sdtsym.h. The value CLASSDIAGRAM (21) should be used.

name

string

Name of the diagram to create.

pageType

integer

Page type Defined in sdtsym.h. The value CLASSPAGE (16) should be used

pageName

string

name of the first page

Service Reply
SEOMECREATEDIAGRAMREPLY

Parameter Type Description
status

integer

Service reply status.

bufId

integer

Refers to a buffer in the editor.

Errors

-

Emitted Notifications

Notification Description
SEOMENEWNOTIFY

As a result of creating the diagram.

Create Text Diagram

Description

Creates an empty text diagram in new buffer. Corresponds to Text Editor command New.

Tools Supporting the Service
SET_TE
Service Request
SETECREATEDIAGRAM

Parameter Type Description
diagramType

integer

Diagram type. See sdtsym.h for valid diagram types.

name

string

Name of the diagram to create.

Service Reply
SETECREATEREPLY

Parameter Type Description
status

integer

Service reply status.

bufId

integer

Refers to a buffer in the editor.

Errors

-

Emitted Notifications

Notification Description
SETENEWNOTIFY

As a result of creating the diagram.

Editor - Object Services

Select Object

Description

The Select Object service will highlight an object in a diagram. Note that this command does not show the buffer and the selected object in a window. The difference between this service and the Obtain GR Reference service is that the Select Object service does not require the diagram to be saved on a file.

Tools Supporting the Service
SET_SDLE 
SET_MSCE 
SET_OME
Service Request
SESELECTOBJECT

Parameter Type Description
bufId

integer

Buffer referencing the diagram in which an object should be shown.

objectid

integer

Identifier to the object to show.

row

integer

The row where to put the text cursor.

column

integer

The column where to put the text cursor in the row.

keepSelections

bool

Flag indicating if old selections should be kept.

Service Reply
SESELECTOBJECTREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid diagram buffer id
Invalid object id
SDLE is busy, syntax error in text   (SDLE only)

Show Object

Description

The Show Object service will make sure that the specified object is visible in a window. This means that it will display the buffer in a window and if necessary scroll into the position where the object is. Often used in combination with Select Object.

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SESHOWOBJECT

Parameter Type Description
bufId

integer

Buffer referencing the diagram in which an object should be shown.

objectId

integer

Identifier to the object to show.

Service Reply
SESHOWOBJECTREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid diagram buffer id
Invalid object id
SDLE is busy, syntax error in text   (SDLE only)

Insert SDL Object

Description

Adds an object to the SDL diagram.

Tools Supporting the Service
SET_SDLE
Service Request
SESDLEINSERTOBJECT

Parameter Type Description
bufId

integer

Buffer in which to insert the object.

pageName

string

Page to insert the object on.

shiftIsDow
n

bool

Emulate behavior of having <Shift> pressed when inserting an symbol.

objectType

integer

Type of object. Valid objects depend on the type of diagram and if syntax checking is on. Corresponds to available symbols in the editor symbol menu.
NOTE: SDL reference symbols are not possible to add using this service.
Definitions of symbols are found in sdtsym.h.

objectText

string

Text in object.

Service Reply
SESDLEINSERTOBJECTREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid diagram buffer id
Invalid object id
A reference symbol containing text\
cannot be inserted in diagram <diagram>
Object type <objectType> is not allowed\
in diagram <diagram>
Unable to open page 
The page is too small to insert the object
SDLE is busy, syntax error in text

Insert MSC Object

Description

The Insert Object service will create a new object in the diagram identified by the parameter and return an object identification (an integer) to the client. It will not display the new object.

For a full specification of how to specify the object to insert, the specification of Message Sequence Charts Z.120 should be consulted or the document "MSC Trace and Log Format 2.0 Specification" available from IBM Rational.

Tools Supporting the Service
SET_MSCE
Service Request
SEINSERTOBJECT

Parameter Type Description
bufId

integer

Buffer in which to insert the object.

afterObject

integer

Only object id 0 is allowed, and adds the object as the last object.

objectDescription

string

Description of the object to insert. The description should be in accordance with Z.120 using event oriented PR. Only one object at the time can be inserted.

Service Reply
SEINSERTOBJECTREPLY

Parameter Type Description
status

integer

Service reply status.

objectId

integer

Identifier to object.

Errors
Invalid diagram buffer id
Errors from parsing objectDescription

Remove Object

Description

The Remove Object service will delete an object in a diagram.

Tools Supporting the Service
SET_MSCE
Service Request
SEREMOVEOBJECT

Parameter Type Description
bufId

integer

Buffer referencing the diagram in which an object should be removed.

objectId

integer

The object to remove.

Service Reply
SEREMOVEOBJECTREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid diagram buffer id
Invalid object id
Object can not be removed   (MSCE only)

Get Object Text

Description

The service will extract all texts for a given object.

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SEGETOBJECTTEXT

Parameter Type Description
bufid

string

A buffer referencing the diagram where the object exists.

objectId

integer

Identifier to the object.

Service Reply
SEGETOBJECTTEXTREPLY

Parameter Type Description
status

integer

Service reply status.

objectType

integer

The type of the object. Definitions of possible object types are found in sdtsym.h.

textnumber

integer

The number of the text strings.

texts

stringlist

All the texts associated to the object.

Errors
Invalid diagram buffer id
No page found with this object id
No object with this id found

Editor - Object Attribute Services

Introduction

It is possible to extend the data associated to an object managed by the SDL Suite with the user's own data. How this is done is described in Figure 161.

Figure 161 : Extending the attributes associated to a symbol

The object can have any number of attributes associated to it, not necessarily 2 as illustrated. The number of extended data attributes is arbitrary.

An object is potentially any item that is handled as a source component by the SDL Suite, or any of the sub-components of which it consists. Objects are thus:

The purpose of the extended data attribute is:

Extended Data Attribute

An extended data attribute defines a number of fields. Below is a few of them further elaborated.

Display Key

Description

Request to display, i.e. select, all symbols referred by SDTRef, that have at least one associated attribute that matches the keys ProprietaryKey and AttributeKey.

SDTRef is typically a diagram, but could also be a page or a specific symbol. The symbols that match the criteria will be marked as selected in the drawing area. Other symbols will be de-selected.

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SEDISPLAYKEY

Parameter Type Description
ProprietaryKey

integer

See the introductory description.

AttributeKey

integer

See the introductory description.

SDTRef

string

See the introductory description.

Service Reply
SEDISPLAYKEYREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
SDT Reference Errors

List Key

Description

Request to list all objects referred by SDTRef, that have at least one associated attribute that matches the keys ProprietaryKey and AttributeKey.

SDTRef is typically a diagram, but could also be a page or a specific symbol. The response is a count and a list of SDTRef to all objects that match the keys.

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SELISTKEY

Parameter Type Description
ProprietaryKey

integer

See the introductory description.

AttributeKey

integer

See the introductory description.

SDTRef

string

See the introductory description.

Service Reply
SELISTKEYREPLY

Parameter Type Description
status

integer

Service reply status.

NoOfKeys

integer

Number of matching keys.

SDTRef*

string

A list of SDT references.

Errors
SDT Reference Errors

Create Attribute

Description

Request add a new attribute to the symbol that matches the SDT reference SDTRef.

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SECREATEATTRIBUTE

Parameter Type Description
ProprietaryKey

integer

A key that allows the external user / tool to distinguish his extensions from other users' / tools'.

AttributeKey

integer

A key that allows the external user / tool to classify his own extension.

SDTRef

string

A valid SDT reference identifying the object.

datainterpret

integer

Defines how data is to be interpreted. Should be set to 0.

comment

string

An explanatory (readable) comment.

MenuChoice

string

The name of the pop-up menu choice that will be appended to the tool's pop-up menu, upon selection of the symbol.

dataLen

integer

Length of data.

data

ByteString

The user's data.

Service Reply
SECREATEATTRIBUTEREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
SDT Reference Errors
Error in match

Update Attribute

Description

Request to update the attribute that matches the search criteria (SDTRef, ProprietaryKey, AttributeKey). If an attribute matches the search keys, then the entire attribute's contents will be updated (replaced) with new contents.

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SEUPDATEATTRIBUTE

Parameter Type Description
ProprietaryKey

integer

A key that allows the external user / tool to distinguish his extensions from other users' / tools'.

AttributeKey

integer

A key that allows the external user / tool to classify his own extension.

SDTRef

string

A valid SDT reference identifying the object.

datainterpret

integer

Defines how data is to be interpreted. The following values are recognized:

Should be set to 0.

comment

string

An explanatory (readable) comment.

MenuChoice

string

The name of the pop-up menu choice that will be appended to the tool's pop-up menu, upon selection of the symbol.

dataLen

integer

Length of data.

data

ByteString

The user's data.

Service Reply
SEUPDATEATTRIBUTEREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
SDT Reference Errors
Error in match

Read Attribute

Description

Request to read the attribute(s) that match(es) the keys and the diagram identified by SDTRef. The SDTRef reference should contain a page attribute.

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SEREADATTRIBUTE

Parameter Type Description
ProprietaryKey

integer

See the introductory description.

AttributeKey

integer

See the introductory description.

SDTRef

string

See the introductory description.

Service Reply
SEREADATTRIBUTEREPLY

Parameter Type Description
status

integer

Service reply status.

DataInterpret

integer

Type of data, always 0.

comment

string

Comment text.

MenuChoice

string

The defined menu choice.

dataLen

integer

Length of binary data.

data

ByteString

Data associated to the extended attribute.

Errors
SDT Reference Errors
Error in match

Delete Attribute

Description

Request to delete the attribute that matches the search criteria (SDTRef, ProprietaryKey, AttributeKey).

Tools Supporting the Service
SET_SDLE
SET_MSCE
SET_OME
Service Request
SEDELETEATTRIBUTE

Parameter Type Description
ProprietaryKey

integer

See the introductory description.

AttributeKey

integer

See the introductory description.

SDTRef

string

See the introductory description.

Service Reply
SEDELETEATTRIBUTEREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
SDT Reference Errors
More than one object match the search
No object match the search

Information Server Services

Load Definition File

Description

Loads a file containing external signal definitions into the Information Server. The contents of such a file are then made available via the Signal Dictionary functionality found in the SDL Editor.

The Information Server could read any ASCII file, but for efficient usage, the format of the files should contain one signal definition per line.

Tools Supporting the Service
SET_INFOSERVER
Service Request
SELOADDEFINITIONMAP

Parameter Type Description
fileName

string

Name of the file to load.

tag

integer

Is used to either add or remove a file.

0 = Add definition

1 = Remove definition.

Service Reply
SELOADDEFINITIONMAPREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
File already added
File was not added before

SDL Editor Services

GRPR

Description

Generate PR for a given binary file. Optionally, GR references and CIF comments could be generated.

If the file is already being edited the PR generated will be from the internal version in the SDL Editor and not from the data in the file.

If the diagram is not being edited it will be unloaded after the PR generation.

Tools Supporting the Service
SET_SDLE
Service Request
SEGRPRP

Parameter Type Description
fileName

string

The file where the SDL/GR is stored.

fileName

string

The file where the PR is written

append

bool

If true, the PR will be appended to the file.

generateGRRef

bool

If true, the generated PR will also contain graphical references, that are used in the Analyzer to backtrace errors.

generateCIF

bool

If true, the PR will also contain CIF comments.

Service Reply
SEGRPRREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid file name
SDLE is busy, syntax error in text   (SDLE only)

Tidy Up

Description

The Tidy Up service will perform a tidy up on a specified diagram. The functionality is identical to the Tidy Up command available in the SDL Editor.

Tools Supporting the Service
SET_SDLE
Service Request
SETIDYUP

Parameter Type Description
bufid

integer

Buffer referencing the diagram to tidy up.

Service Reply
SETIDYUPREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid diagram buffer id

SC Editor Services

Get Diagram Info

Description

Get information about the symbols and lines of a SC diagram. The format of the returned infoList is:

Symbols: <noOfSymbols>
<type> <id> <superstateId> <noOfTexts> <text1> ...
...
Lines: <noOfLines>
<type> <fromSymbolId> <toSymbolId> <noOfTexts> <text1> ...
...


Where:
<type> ::=	 	 An integer denoting the type of symbol or line
	 	 Types can be found in sdtsym.h
<id> ::= 	 	 An integer identifying a symbol

Tools Supporting the Service
SET_OME
Service Request
SEGETDIAGRAMINFO

Parameter Type Description
bufId

integer

Refers to a buffer in the editor.

Service Reply
SEGETDIAGRAMINFOREPLY

Parameter Type Description
status

integer

Service reply status.

infoList

stringList

The symbols and lines of the diagram.

Errors
Invalid diagram buffer id
Invalid diagram type

MSC Editor Services

MSC GRPR

Description

Generate PR for a given MSC binary file. Optionally, GR references can be generated.

If the file is already being edited, the generated PR will be from the internal version in the MSC Editor and not from the data in the file.

If the diagram is not being edited it will be unloaded after the PR generation.

Tools Supporting the Service
SET_MSCE
Service Request
SEMSCGRPR

Parameter Type Description
fileName

string

The file where the MSC/GR is stored.

fileName

string

The file where the PR is written.

mscDocName

string

The name of the MSC document. If empty the PR will be appended to PR file.

generateGRRef

bool

If true, the generated PR will also contain graphical references, that are used in the Analyzer to backtrace errors.

Service Reply
SEMSCGRPRREPLY

Parameter Type Description
errors

integer

Number of errors in the GR file.

warnings

integer

Number of warnings in the GR file.

errorLog

string

Description of errors and warnings, with GR references.

MSC Generate cui script

Description

Generate cui script for a given MSC diagram.

If the file is already being edited, the generated script will be from the internal version in the MSC Editor and not from the data in the file.

If the diagram is not being edited it will be unloaded after the script generation.

The input script will be generated as a .cui file with the same name as the input MSC diagram. The .cui file will be located in the same directory as your input MSC.

Tools Supporting the Service
SET_MSCE
Service Request
SEGENERATEINPUTSCRIPT

Parameter Type Description
fileName

string

The file where the MSC/GR is stored.

Service Reply
SEGENERATEINPUTSCRIPTREPLY

Parameter Type Description
status

integer

Service reply status.

HMSC Editor Services

HMSC GRPR

Description

Generate PR for a given HMSC binary file. Optionally, GR references can be generated.

If the file is already being edited, the generated PR will be from the internal version in the HMSC Editor and not from the data in the file.

If the diagram is not being edited it will be unloaded after the PR generation.

Tools Supporting the Service
SET_OME
Service Request
SEHMSCGRPR

Parameter Type Description
fileName

string

The file where the HMSC/GR is stored.

fileName

string

The file where the PR is written.

mscDocName

string

The name of the HMSC document. If empty the PR will be appended to PR file.

generateGRRef

bool

If true, the generated PR will also contain graphical references, that are used in the Analyzer to backtrace errors.

Service Reply
SEHMSCGRPRREPLY

Parameter Type Description
errors

integer

Number of errors in the GR file.

warnings

integer

Number of warnings in the GR file.

errorLog

string

Description of errors and warnings, with GR references.

CIF Services

The CIF services enables the user to create diagrams where the graphical objects and texts could be positioned in a controlled manner.

These services enables the user to build converters to SDL Suite diagram formats.

The diagram types which are supported are:

where the services are supported by the SDL Editor, and

where the services are supported by the OM Editor.

Create SDL Diagram

Description

Creates an empty SDL diagram in a new buffer. Corresponds to the SDL Editor command New. The defaults applied to the created page are defined for the Create SDL Page service.

The texts for the package reference and the headings will be shown on every page in the diagram. The package reference symbol and the heading symbols will be automatically created, but their size can be changed by using the Insert SDL Object service for these symbols, (see Object Specific Parameters).

The kernel heading will be parsed to extract the necessary attributes like the virtuality, diagram type and diagram name. If this parsing fails the service will return an error.

The splitting of the SDL heading into a kernel heading and an additional heading is done according to the rules in section 2.2.5 `Partitioning of diagrams' in Z.100 with some necessary exceptions. Normally the kernel heading contains the heading up to, and including the diagram name,

<kernel heading> ::= [<virtuality>] <diagram kind> 
{<diagram name> | <diagram identifier>}

The following exceptions to this rule apply:

For a type based system diagram the kernel heading contains the complete definition except for the ending <end> clause.

<kernel heading> ::= <typebased system heading>

For a process diagram the <number of process instance> might be included in the kernel heading.

For a procedure diagram the kernel heading is

<kernel heading> ::= <procedure preamble> procedure 
{<procedure name> | <procedure identifier>}
Tools Supporting the Service
SET_SDLE
Service Request
SESDLECIFCREATEDIAGRAM

Parameter Type Description
packageReferenceText

string

The text that will appear in the package reference symbol

kernelHeadingText

string

The text that will appear in the kernel heading symbol

AdditionalHeadingText

string

The text that will appear in the additional heading symbol

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.

pageWidth

integer

The width of the page.

pageHeight

integer

The height of the page.

gridWidth

integer

The grid width.

gridHeight

integer

The grid height.

autonumbered

bool

If true the page is an autonumbered page.

showMeFirst

bool

If true this page is set as the ShowMeFirst page.

scale

integer

The scale used when shown, 100 means a 1:1 scale.

Service Reply
SESDLECIFCREATEDIAGRAMREPLY

Parameter Type Description
status

integer

Service reply status.

bufid

integer

Refers to a buffer in the editor.

Errors
The pagename is empty
Illegal diagram kernel heading
Emitted Notifications

Notification Description
SESDLENEWNOTIFY

As a result of creating the diagram.

SEPAGENOTIFY

As a result of creating a page.

Create SDL Page

Description

The Create Page service will create a new page in an existing diagram. The new page will be inserted as the last page in the diagram. The created page will have a frame symbol with margins to the page border as defined by the actual preference file. The kernel heading, additional heading and page number symbols exists and are placed automatically relative to the frame symbol. The package reference symbol exists, automatically placed, if the page type is a system page or a package page. The frame symbol can be changed to another position by using the Insert SDL Object service.

If a page already exists with the given page name, the service will be ignored and the return status is OK. This can be used for convenience to always send Create Page for all pages including the one already sent in the Create SDL Diagram.

The grid values should be multiples of 5 mm. If the values are zero or less than zero this means that the preferences values are used for the grid values.

A page can be set to be autonumbered. When this is used a page name must be given as well. For consecutive autonumbered pages these names must be "1", "2", "3" and so on. It will be checked that the given page name is the same as the generated page name. If not an error will be returned.

If the ShowMeFirst attribute is set for a new page it will override an already existing ShowMeFirst page.

Tools Supporting the Service
SET_SDLE
Service Request
SESDLECIFCREATEPAGE

Parameter Type Description
bufId

integer

Buffer referencing the diagram in which the page will be created.

pageType

integer

Type of the 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 new page in the diagram.

pageWidth

integer

The width of the page.

pageHeight

integer

The height of the page.

gridWidth

integer

The grid width.

gridHeight

integer

The grid height.

autonumbered

bool

If true the page is an autonumbered page.

showMeFirst

bool

If true this page is set as the ShowMeFirst page.

scale

integer

The scale used when shown, 100 means a 1:1 scale.

Service Reply
SESDLECIFCREATEPAGEREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid diagram buffer id
The pagename is empty
Command canceled in add page
For autonumbered pages, the given pagename "2" must 
be the same as the generated page name "1"
Emitted Notifications

Notification Description
SEPAGENOTIFY

As a result of creating a page.

Insert SDL Object

Description

The Insert Object service will insert an object in a specified position at a specific page. The return value is the object id for the inserted object. Lines connected to the inserted symbol should refer to the objectId returned by this service.

The following checks are applied on parameters:

The following is a non-exhaustive list of restrictions, applied inside SDLE when manipulating with symbols, that are not checked by this service:

Tools Supporting the Service
SET_SDLE
Service Request
SESDLECIFINSERTOBJECT

Parameter Type Description
bufId

integer

Buffer referencing the diagram in which an object should be shown.

pagename

string

An existing page within the diagram.

objectType

integer

Identify the type of object to insert. Valid values for all symbols are given in sdtsym.h. For lines the values are listed below.

updateFlag

bool

If this flag is true a routine will be called for this page to fix some attributes for the objects. This fixing must be done before the page is saved. If this flag is false this fix will not be done.

object 
specific 
parameters

varying

One or more parameters defining the inserted object.

Service Reply
SESDLECIFINSERTOBJECTREPLY

Parameter Type Description
status

integer

Service reply status.

objectId

integer

Identifier to the inserted object.

Errors
Invalid diagram buffer id
Invalid pagename
Invalid fromSymbol id for a line: 
Invalid toSymbol id for a line: 
Invalid fromSymbol. The fromSymbol is a line: 
Invalid toSymbol. The toSymbol is a line: 
Number of points in line < 2 : 
Invalid objectId for ConnectionPoint line: 
Invalid object type:
Object Specific Parameters

For each object type the needed parameters are listed. All coordinates are given in 1/10 mm units in the coordinate system with the upper left corner of the page as origo and the y-coordinate having the positive direction going downwards.

A given coordinate will be adjusted to fall on a grid. For symbols this grid is given by a grid net of 5 x 5 mm. For line breakpoints and text positions the grid net is 2.5 x 2.5 mm.

The Pagenumber symbol (objectType number 53) has no extra specific parameters. When inserted there will not be a new symbol created as the pagenumber symbol is always created when the page is created. The text for the pagenumber symbol is generated automatically. The only use of inserting this symbol is to force an update of the page by having the updateFlag set to true.

Parameter Type Description
left

integer

The x coordinate for the left side.

top

integer

The y coordinate for the top side.

width

integer

The width of the symbol.

height

integer

The height of the symbol.

text

string

The text in the symbol. The text is automatically aligned according to the built-in routines in SDLE

Parameter Type Description
left

integer

The x coordinate for the left side.

top

integer

The y coordinate for the top side.

width

integer

The width of the symbol.

height

integer

The height of the symbol.

dashed

bool

If true the symbol will be dashed, this is valid for block, process and service symbols.

text

string

The text in the symbol.

XtextPosition

integer

The x coordinate for the left top position of the text.

YtextPosition

integer

The y coordinate for the left top position of the text.

There is no check that the text will fall inside the symbol boundary.

Parameter Type Description
left

integer

The x coordinate for the left side.

top

integer

The y coordinate for the top side.

width

integer

The width of the symbol.

height

integer

The height of the symbol.

text

sString

The text in the symbol.

An automatically sized TextSymbol shall have the width and height set to zero. If values are given this means that the symbol will be clipped using the given sizing values.

Parameter Type Description
left

integer

The x coordinate for the left side (Comment, TextExtension) or the right side (CommentLeft, TextExtensionLeft)

top

integer

The y coordinate for the top side.

text

string

The text in the symbol.

For a CommentLeft or TextExtensionLeft the position gives the right top corner of the symbol. The size is automatically adjusted.

Parameter Type Description
left

integer

The x coordinate for the left side.

top

integer

The y coordinate for the top side.

width

integer

The width of the symbol.

height

integer

The height of the symbol.

A default FrameSymbol will always exist on a created page. This service will replace the existing Frame with a new frame symbol at the given position with the new size. The existing heading symbols, package reference symbol and the pagenumber symbol will be automatically adjusted.

Parameter Type Description
width

integer

The width of the symbol.

height

integer

The height of the symbol.

For automatically sized symbols the values for the width and the height should be zero. If values different from zero are given this means that the symbol will be clipped.
Note that it might be necessary to insert this symbol for every page. This is so because these symbols might have a unique size for every page. If the symbols are not clipped there is no need to insert the symbol as they will be automatically generated as an unclipped symbol.
The size of the kernel heading cannot be changed.

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts.

toID

integer

The objectId for the symbol where the line ends.

textExists

bool

Is true if there is text on the flow line.

text

string

Optional text in the message. Only exists if textExists is true.

XtextPosition

integer

Optional text position in the message. Only exists if textExists is true. x coordinate for the left top corner of the text.

YtextPosition

integer

Optional text position in the message. Only exists if textExists is true. y coordinate for the left top corner of the text.

dashed

bool

If true the line will be dashed.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

It is checked that symbols exist having the given fromID and toID. The text and text position shall only exist if the textExists flag is true. Flowlines after Decision, TransitionOption and MacroCall should always have text. There will be numPoints x and y-values at the end of the message. Line coordinates are adjusted to the nearest grid point but it will not be checked whether line endpoints are placed on the symbol boundaries, as they are expected to be.

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts. Zero means ENV.

toID

integer

The objectId for the symbol where the line ends. Zero means ENV.

name

string

The name of the signal route.

signalList

string

The text in the signal list.

XnamePosition

integer

The x coordinate for the left top position of the name.

YnamePosition

integer

The y coordinate for the left top position of the name.

XsignalListPosition

integer

The x coordinate for the left top position of the signal list.

YsignalListPosition

integer

The y coordinate for the left top position of the signal list.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

It is checked that symbols exists having the given fromID and toID. There will be numPoints x and y-values at the end of the message. Text position and line coordinates are adjusted to the nearest grid point but it will not be checked whether line endpoints are placed on the symbol boundary (the rectangle enclosing the symbol), as they are expected to be. Extra line segments needed for e.g. a signal route entering a service will be automatically generated.

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts. Zero means ENV.

toID

integer

The objectId for the symbol where the line ends. Zero means ENV.

name

string

The name of the signal route.

signalList1

string

The text in the signal list in the direction from fromID to toID.

signalList2

string

The text in the signal list in the reversed direction.

XnamePosition

integer

The x coordinate for the left top position of the name.

YnamePosition

integer

The y coordinate for the left top position of the name.

XsignalList1Position

integer

The x coordinate for the left top position of the first signal list.

YsignalList1Position

integer

The y coordinate for the left top position of the first signal list.

XsignalList2Position

integer

The x coordinate for the left top position of the second signal list.

YsignalList2Position

integer

The y coordinate for the left top position of the second signal list.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts. Zero means ENV.

toID

integer

The objectId for the symbol where the line ends. Zero means ENV.

name

string

The name of the channel.

signalList

string

The text in the signal list.

XnamePosition

integer

The x coordinate for the left top position of the name.

YnamePosition

integer

The y coordinate for the left top position of the name.

XsignalListPosition

integer

The x coordinate for the left top position of the signal list.

YsignalListPosition

integer

The y coordinate for the left top position of the signal list.

XarrowPosition

integer

The x coordinate for the arrow.

YarrowPosition

integer

The y coordinate for the arrow.

noDelay

bool

If true the channel is a non delaying channel.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

It is checked that symbols exists having the given fromID and toID. There will be numPoints x and y-values at the end of the message. Text position and line coordinates are adjusted to the nearest grid point but it will not be checked whether line endpoints are placed on the symbol boundary (the rectangle enclosing the symbol), as they are expected to be. The arrow position are automatically adjusted to be placed at the line as close as possible to the given arrow point. The angle of the arrow is automatically calculated. For a non delaying channel the arrow position is ignored and it will be automatically placed at the last breakpoint.

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts. Zero means ENV.

toID

integer

The objectId for the symbol where the line ends. Zero means ENV.

name

string

The name of the channel.

signalList1

string

The text in the signal list in the direction from fromID to toID.

signalList2

sString

The text in the signal list in the reversed direction.

XnamePosition

integer

The x coordinate for the left top position of the name.

YnamePosition

integer

The y coordinate for the left top position of the name.

XsignalList1Position

integer

The x coordinate for the left top position of the first signal list.

YsignalList1Position

integer

The y coordinate for the left top position of the first signal list.

XsignalList2Position

integer

The x coordinate for the left top position of the second signal list.

YsignalList2Position

integer

The y coordinate for the left top position of the second signal list.

Xarrow1Position

integer

The x coordinate for the first arrow.

Yarrow1Position

integer

The y coordinate for the first arrow.

Xarrow2Position

integer

The x coordinate for the second arrow.

Yarrow2Position

integer

The y coordinate for the second arrow.

noDelay

bool

If true the channel is a non delaying channel.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts. This object is a channel for the ChannelSubstructureLine.

toID

integer

The objectId for the symbol where the line ends.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

It is checked that symbols exists having the given fromID and toID. There will be numPoints x and y-values at the end of the message. Line coordinates are adjusted to the nearest grid point but it will not be checked whether line endpoints are placed on the symbol boundary, as they are expected to be. For a ChannelSubstructureLine the starting is adjusted to be placed on the channel.

Parameter Type Description
X

integer

The x coordinate for the gate position on the FrameSymbol boundary.

Y

integer

The y coordinate for the gate position on the FrameSymbol boundary.

dashed

bool

If true the gate is dashed.

name

string

The name of the gate.

signalList

string

The text in the signal list.

constraint

string

The text in the constraint symbol connected to the gate.

XnamePosition

integer

The x coordinate for the left top position of the name.

YnamePosition

integer

The y coordinate for the left top position of the name.

XsignalListPosition

integer

The x coordinate for the left top position of the signal list.

YsignalListPosition

integer

The y coordinate for the left top position of the signal list.

The length of the gate is automatically calculated, so also the arrow position. The point will be adjusted such that it is guaranteed to stay on the Frame boundary. If the frame symbol is inserted after a gate, the gate might be positioned outside the frame. The correct positions will be fixed in the update that must be performed before saving the page.

Parameter Type Description
X

integer

The x coordinate for the gate position on the FrameSymbol boundary.

Y

integer

The y coordinate for the gate position on the FrameSymbol boundary.

dashed

bool

If true the gate is dashed.

name

string

The name of the gate.

signalList1

string

The text in the signal list in the direction into the diagram.

signalList2

string

The text in the signal list in the direction out of the diagram.

constraint

string

The text in the constraint symbol connected to the gate.

XnamePosition

integer

The x coordinate for the left top position of the name.

YnamePosition

integer

The y coordinate for the left top position of the name.

XsignalList1Position

integer

The x coordinate for the left top position of the first signal list.

YsignalList1Position

integer

The y coordinate for the left top position of the first signal list.

XsignalList2Position

integer

The x coordinate for the left top position of the second signal list.

YsignalList2Position

integer

The y coordinate for the left top position of the second signal list.

Parameter Type Description
objectID

integer

The objectId for the symbol where the ConnectionPoint exists. Zero means ENV.

X

integer

The x coordinate for the ConnectionPoint.

Y

integer

The y coordinate for the ConnectionPoint.

name

string

The name of the ConnectionPoint.

XnamePosition

integer

The x coordinate for the left top position of the name.

YnamePosition

integer

The y coordinate for the left top position of the name.

A ConnectionPoint is used for gate names on the Frame symbol (ENV), channel names in block diagrams for graphical connect statements and for gate names inside block/process/service instances of block/process/service types. The objectID must be a valid symbol. The coordinate is adjusted such that the point will fall on the symbol boundary. If the frame symbol is inserted after a connection point residing on the frame, it might be positioned outside the frame. The correct positions will be fixed in the update that must be performed before saving the page.

Create OM Diagram

Description

Creates an empty OM diagram in a new buffer. Corresponds to the OM Editor command New. The defaults applied to the created page are defined for the Create OM Page service.

Tools Supporting the Service
SET_OME
Service Request
SEOMECIFCREATEDIAGRAM

Parameter Type Description
name

string

Diagram name.

pageName

string

Name of the first page in the diagram.

pageWidth

integer

The width of the page.

pageHeight

integer

The height of the page.

gridWidth

integer

The grid width.

gridHeight

integer

The grid height.

autonumbered

bool

If true the page is an autonumbered page.

showMeFirst

bool

If true this page is set as the ShowMeFirst page.

scale

integer

The scale used when shown, 100 means a 1:1 scale.

Service Reply
SEOMECIFCREATEDIAGRAMREPLY

Parameter Type Description
status

integer

Service reply status.

bufid

integer

Refers to a buffer in the editor

Errors
The pagename is empty
Emitted Notifications

Notification Description
SEOMENEWNOTIFY

As a result of creating the diagram.

SEPAGENOTIFY

As a result of creating a page.

Create OM Page

Description

The Create Page service will create a new page in an existing diagram. The new page will be inserted as the last page in the diagram. The heading and page number symbols exists and are placed automatically relative to the frame symbol. The frame symbol can not be changed to another position.

If a page already exists with the given page name, the service will be ignored and the return status is OK. This can be used for convenience to always send Create Page for all pages including the one already sent in the Create OM Diagram service.

The grid values should be multiples of 5 mm. If the values are zero or less than zero this means that the preferences values are used for the grid values.

A page can be set to be autonumbered. When this is used a page name must be given as well. For consecutive autonumbered pages these names must be "1", "2", "3" and so on. It is considered an error if the given page name not is the same as the generated page name when this flag is set.

If the ShowMeFirst attribute is set for a new page it will override an already existing ShowMeFirst page.

Tools Supporting the Service
SET_OME
Service Request
SEOMECIFCREATEPAGE

Parameter Type Description
bufId

integer

Buffer referencing the diagram in which the page will be created.

pageName

string

Name of the new page in the diagram.

pageWidth

integer

The width of the page.

pageHeight

integer

The height of the page.

gridWidth

integer

The grid width.

gridHeight

integer

The grid height.

autonumbered

bool

If true the page is an autonumbered page.

showMeFirst

bool

If true this page is set as the ShowMeFirst page.

scale

integer

The scale used when shown, 100 means a 1:1 scale.

Service Reply
SEOMECIFCREATEPAGEREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Invalid diagram buffer id
The pagename is empty
For an autonumbered page the given name must be the 
same as the generated pagename: "<gen.pagename>"
Emitted Notifications

Notification Description
SEPAGENOTIFY

As a result of creating a page.

Insert OM Object

Description

The Insert Object service will insert an object in a specified position at a specific page. The return value is the object id for the inserted object. Lines connected to the inserted symbol should refer to the objectId returned by this service.

The following parameter checks are performed:

The following is a non-exhaustive list of restrictions, applied inside OME when manipulating with symbols, that are not checked by this service:

Tools Supporting the Service
SET_OME
Service Request
SEOMECIFINSERTOBJECT

Parameter Type Description
bufId

integer

Buffer referencing the diagram in which an object should be shown.

pagename

string

An existing page within the diagram.

objectType

integer

Identify the type of object to insert. Valid values for all symbols are given in sdtsym.h. For lines the values are listed below.

updateFlag

bool

If this flag is true a routine will be called for this page to fix some attributes for the objects. This fixing must be done before the page is saved. If this flag is false this fix will not be done.

object 
specific 
parameters

varying

One or more parameters defining the inserted object.

Service Reply
SEOMECIFINSERTOBJECTREPLY

Parameter Type Description
status

integer

Service reply status.

objectId

integer

Identifier to the inserted object

Errors
Invalid diagram buffer id
Invalid pagename
Invalid fromSymbol id for a line: 
Invalid toSymbol id for a line: 
Invalid fromSymbol. The fromSymbol is a line: 
Invalid toSymbol. The toSymbol is a line: 
Number of points in line < 2 : 
Invalid objectId for ConnectionPoint line: 
Invalid object type: 
Object Specific Parameters

For each object type the needed parameters are listed below. All coordinates are given in 1/10 mm units in the coordinate system with the upper left corner of the page as origo and the y-coordinate having the positive direction going downwards.

A given coordinate will be adjusted to fall on a grid. For symbols this grid is given by a grid net of 5 x 5 mm. For line breakpoints and text positions the grid net is 2.5 x 2.5 mm.

The Pagenumber symbol (objectType number 53) have no extra specific parameters. When inserted there will not be a new symbol created as the pagenumber symbol is always created when the page is created. The text for the pagenumber symbol is generated automatically. The only use of inserting this symbol is to force an update of the page by having the updateFlag set to true

Parameter Type Description
left

integer

The x coordinate for the left side.

top

integer

The y coordinate for the top side.

nameText

string

The name text part of the symbol.

attributeText

string

The attribute text part of the symbol.

operationText

string

The operation text part of the symbol.

stereotypeText

string

The stereotype text part of the symbol.

propertiesText

string

The properties text part of the symbol.

collapsed

bool

If this is true the symbol is collapsed.

Parameter Type Description
left

integer

The x coordinate for the left side.

top

integer

The y coordinate for the top side.

nameText

string

The name text part of the symbol.

attributeText

string

The attribute text part of the symbol.

stereotypeText

string

The stereotype text part of the symbol.

propertiesText

string

The properties text part of the symbol.

collapsed

bool

If this is true the symbol is collapsed.

Parameter Type Description
left

integer

The x coordinate for the left side.

top

integer

The y coordinate for the top side.

text

string

The text in the symbol.

collapsed

bool

If this is true the symbol is collapsed

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts.

toID

integer

The objectId for the symbol where the line ends.

haveName

bool

Flag set if the line has forward name attributes

name

string

Only if haveName set: The forward name of the line.

nameArrow

bool

Only if haveName set: Arrow on the forward name.

XPosition

integer

Only if haveName set: The x coordinate for the left top position of the name.

YPosition

integer

Only if haveName set: The y coordinate for the left top position of the name.

haveRevName

bool

Flag set if the line has reversed name attributes.

revName

string

Only if haveRevName set: The reversed name of the line.

revNameArrow

bool

Only if haveRevName set: Arrow on the reversed name.

XPosition

integer

Only if haveRevName set: The x coordinate for the left top position of the reversed name.

YPosition

integer

Only if haveRevName set: The y coordinate for the left top position of the reversed name.

haveRoleName

bool

Flag set if the line has role name attributes.

roleName

string

Only if haveRoleName set: The forward role name of the line.

XPosition

integer

Only if haveRoleName set: The x coordinate for the left top position of the forward role name.

YPosition

integer

Only if haveRoleName set: The y coordinate for the left top position of the forward role name.

haveRevRoleName

bool

Flag set if the line has reversed role name attributes.

revRoleName

string

Only if haveRevRoleName set: The reversed role name of the line.

XPosition

integer

Only if haveRoleName set: The x coordinate for the left top position of the reversed role name.

YPosition

integer

Only if haveRoleName set: The y coordinate for the left top position of the reversed role name.

haveMultText

bool

Flag set if the line has multiplicity text attributes.

multText

string

Only if haveMultText set: The forward multiplicity text of the line.

XPosition

integer

Only if haveMultText set: The x coordinate for the left top position of the multiplicity text.

YPosition

integer

Only if haveMultText set: The y coordinate for the left top position of the multiplicity text.

haveRevMultText

bool

Flag set if the line has reversed multiplicity text attributes.

revMultText

string

Only if haveRevMultText set: The reversed multiplicity text of the line.

XPosition

integer

Only if haveRevMultText set: The x coordinate for the left top position of the multiplicity text.

YPosition

integer

Only if haveRevMultText set: The y coordinate for the left top position of the multiplicity text.

haveQualText

bool

Flag set if the line has qualifier text attributes.

qualText

string

Only if haveQualText set: The forward qualifier text of the line.

haveRevQualText

bool

Flag set if the line has reversed qualifier text attributes.

revQualText

string

Only if haveRevQualText set: The reversed qualifier text of the line.

haveConstText

bool

Flag set if the line has constraint text attributes.

constraintText

string

Only if haveConstText set: The constraint text of the line.

XPosition

integer

Only if haveConstText set: The x coordinate for the left top position of the constraint text.

YPosition

integer

Only if haveConstText set: The y coordinate for the left top position of the constraint text.

haveOrdered

bool

Flag set if the line has the Ordered attribute.

XPosition

integer

Only if haveOrdered set: The x coordinate for the left top position of the Ordered text.

YPosition

integer

Only if haveOrdered set: The y coordinate for the left top position of the Ordered text.

haveSorted

bool

Flag set if the line has the Sorted attribute.

XPosition

integer

Only if haveSorted set: The x coordinate for the left top position of the Sorted text.

YPosition

integer

Only if haveSorted set: The y coordinate for the left top position of the Sorted text.

haveRevOrdered

bool

Flag set if the line has the reversed Ordered attribute.

XPosition

integer

Only if haveRevOrdered set: The x coordinate for the left top position of the reversed Ordered text.

YPosition

integer

Only if haveRevOrdered set: The y coordinate for the left top position of the reversed Ordered text.

haveRevSorted

bool

Flag set if the line has the reversed Sorted attribute.

XPosition

integer

Only if haveRevSorted set: The x coordinate for the left top position of the reversed Sorted text.

YPosition

integer

Only if haveRev Sorted set: The y coordinate for the left top position of the reversed Sorted text.

derived

bool

Flag set if the line shall be marked as derived.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

It is checked that symbols exists having the given fromID and toID. There will be numPoints x and y-values at the end of the message. Text position and line coordinates are adjusted to the nearest grid point but it will not be checked whether line endpoints are placed on the symbol boundary (the rectangle enclosing the symbol), as they are expected to be. Extra line segments needed for e.g. a signal route entering a service will be automatically generated.

Parameter Type Description
fromID

integer

The objectId for the symbol where the line starts.

toID

integer

The objectId for the symbol where the line ends.

haveName

bool

Flag set if the line has a name attribute.

name

QuotedString

Only if haveName set: The name of the line.

XnamePosition

integer

Only if haveName set: The x coordinate for the left top position of the name.

YnamePosition

integer

Only if haveName set: The y coordinate for the left top position of the name.

numPoints

integer

The number of breakpoints for the line. There must be at least 2.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

It is checked that symbols exists having the given fromID and toID. There will be numPoints x and y-values at the end of the message. Text position and line coordinates are adjusted to the nearest grid point.

Parameter Type Description
fromID

integer

The objectId for the line where the link line starts.

toID

integer

The objectId for the symbol where the line ends.

numPoints

integer

The number of breakpoints for the line. Always 2 since no breakpoints are allowed on this line.

x

integer

x coordinate for a point.

y

integer

y coordinate for a point.

It is checked that symbols exists having the given fromID and toID. Observe that the fromID must denote an association or aggregation line. Note that numPoints always must be 2, and consequently there will be two x and y coordinates.

Text Editor Services

Show Position

Description

The Show Position service makes sure that a certain character specified by line and column is visible in a text editor window:

Note that the actual display position after re-centering is undefined if the line and/or column values do not make sense.

Tools Supporting the Service
SET_TE
Service Request
SETESHOWPOSITION

Parameter Type Description
bufid

integer

Identifies the buffer

line

integer

Indicates the line that should be shown

column

integer

Indicates which character on the line which should be shown

Service Reply
SETESHOWPOSITIONREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Buffer id does not exist

Select Text

Description

The Select Text service selects a range of text in a window displaying a given text buffer.

Note that the actual selection is undefined if one or more of the line and/or column values do not make sense.

Tools Supporting the Service
SET_TE
Service Request
SETESELECTTEXT

Parameter Type Description
bufid

integer

Identifies the buffer

line1

integer

Indicates where the selection should start

column1

integer

Indicates the character where the selection should start.

line2

integer

Indicates the line where the selection should end.

column2

integer

Indicates the character where the selection should end.

Service Reply
SETESELECTTEXTREPLY

Parameter Type Description
status

integer

Service reply status.

Errors
Buffer id does not exist
1

In Windows, the SDL Simulator/Explorer UI's can not read menu-definition files.

2

In Windows, the SDL Simulator/Explorer UI's can not read menu-definition files.

3

In Windows, the SDL Simulator/Explorer UI's can not read menu-definition files.

4

In Windows, the SDL Simulator/Explorer UI's can not read menu-definition files.


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